unified-ble-manager 4.0.5 → 4.0.6

package/CHANGELOG.md

@@ -2,7 +2,39 @@
 
 All notable changes to `unified-ble-manager` are documented here.
 
-## [Unreleased]
+## [4.0.6] - 2026-08-26
+
+The first release cut against a live peripheral on Android as well as Linux. Most of it is defects that only real hardware surfaced, several of them boundaries that discarded evidence and so presented a specific fault as silence. Does not retag `v4.0.5`.
+
+### Fixes
+
+- A Tauri disconnect that fails no longer leaves the peer owned when the platform can prove it was released. btleplug's CoreBluetooth `disconnect()` never resolves once the peripheral has left its internal map, so the call is bounded and the outcome decided by a fresh state reading: gone means released, still connected means the retry keeps ownership. On BlueZ the state reading is classified before it is stringified, because a removed D-Bus device object is not a failed question but the answer to it - previously that case was treated as unknowable and the peer stayed owned until the process restarted. Genuine indeterminacy - a D-Bus timeout, the daemon gone, the adapter pulled - still retains ownership (#145, #154).
+
+- BlueZ no longer reports a pairing it could not stop as `cancelled`. `Device1.CancelPairing` rejections were all swallowed, so a refusal from bluetoothd — `org.bluez.Error.Failed`, `NotAuthorized`, a D-Bus timeout, the daemon gone — left the in-flight `Pair` running while `cancelPairing()` returned `cancelled` and the abort/deadline path did the same. A caller told no bond exists while one is still being made cannot recover, because it never learns to look. Only the two rejections that prove nothing is left running are treated as success — `org.bluez.Error.DoesNotExist` and `org.freedesktop.DBus.Error.UnknownObject`, an answer to the question rather than a failure to answer it, the same pair the Tauri disconnect path classifies for the same reason. Anything else now surfaces as `platform.failure` carrying the D-Bus error name (#143).
+
+- `scan()` works on React Native Android again, and so does every other control-plane operation there. The Android dispatcher stamped a hardcoded `1` on field 1 of every result and event it built while the native codec has required version 2 since the schema was frozen, so all of them — `scanStarted`, a connect completing, a connect failing, a cancellation, a bond state change, a lost link — were rejected at the JSI boundary as version-incompatible and dropped. A scan therefore never received its terminal: the radio discovered the peripheral 38 times in one four-minute capture and the application was handed nothing. The stamp now comes from the generated `NATIVE_PROTOCOL_VERSION`, so it cannot drift from the version the codec validates against (#140).
+- A record the codec refuses is no longer only written to logcat: the Android binding counts quarantined records per attachment and emits a `recordQuarantined` diagnostic in place of the record it could not deliver, so an application learns that the boundary discarded something it was asked to deliver (#140).
+- A version-incompatible record names its kind, the version it carried and the version expected, so a quarantined record identifies its emitter instead of leaving four record kinds to choose between (#140).
+- `adapter.waitUntilReady()` no longer reports a radio that is still starting up as one the caller is not permitted to use. The React Native Android boundary answers `authorization: 'unavailable'` until the radio publishes its first authoritative state, and the readiness gate maps that value to `permission.denied` — so the one API whose purpose is to wait that window out failed on the very state it exists to wait for, on a phone with Bluetooth switched on and all four runtime permissions granted. The pending snapshot now reports `authorization: 'unknown'`, the value its `availability` and `power` siblings already carried for the same reason: the absence of a measurement is never a denial, so no readiness gate may block on it (#156).
+- BlueZ states its connection-control truth instead of omitting the concept: `connection:priority` and `connection:parameters` are now registered as explicitly `unsupported`, with limitations naming the BlueZ D-Bus gap (no LE connection-parameter API on `org.bluez.Device1`/`Adapter1`, BlueZ 5.85), the privilege requirement of the alternatives (`CAP_NET_ADMIN` kernel mgmt socket and root-only debugfs — neither a live per-connection update), and the consequence that GATT traffic may run at a multi-hundred-millisecond peer-negotiated interval. `requestPriority()`, `parameters()`, and `parameterEvents()` fail closed with that reason attached (`BleError.limitations` and `platform.safeMessage`) instead of a bare `capability.unsupported` that taught nothing while a slow link looked like a peripheral fault (#149).
+- BlueZ `security.pair()` no longer fires `Device1.Pair` when the operation is aborted or times out while the just-works agent is still registering; it re-checks cancellation after agent registration so a cancelled pairing never proceeds on the daemon (#143).
+- BlueZ `security.pair()` reports `paired` (not `cancelled`) when an abort or deadline lands after `Device1.Pair` has already completed the bond, so a bond that was actually created is never reported as if it never happened (#143).
+- Android `security.pair()` no longer reports a timed-out pairing as `cancelled` when native cancellation is unavailable and it cannot actually stop the in-flight bond; the deadline path now fails closed with `capability.unsupported`, matching the abort path, so a bond that may still complete is never misreported as cancelled (#143).
+
+### Additions
+
+- `FindOptions` accepts `duplicates` and `delivery`, so the `find()` convenience can be pointed at a peripheral that advertises in dense bursts instead of being abandoned for a hand-driven `scan()`. Both default to the values `find()` has always used (`'coalesced'` and `'latest'`), so nothing changes for existing callers (#148).
+- BlueZ pairing dispatch: `org.bluez.Device1.Pair`, `org.bluez.Device1.CancelPairing`, and `org.bluez.Adapter1.RemoveDevice` are now allowed through the dbus-next boundary, and the backend registers a just-works (`NoInputNoOutput`) `org.bluez.Agent1` on its own bus (not the system default) so a client-initiated pairing can complete without an external agent (#141, #143).
+
+### Changes
+
+- The Node convenience factories (`createBluezBleManager` and siblings) now select the first adapter (ordered deterministically by id) when the caller names no `adapterId`, instead of failing on a multi-adapter host. A single-adapter machine needs no configuration and a multi-adapter host picks the same controller every run; pass `adapterId` to target a specific controller (e.g. a second USB dongle used for debugging). The low-level provider is unchanged: it still requires an explicit selection and never silently substitutes one (#143).
+- `PairOptions.secureConnections` (`'require' | 'prefer' | 'disallow'`, default `'prefer'`): request an LE pairing generation. `'prefer'` defers to the platform. No current backend exposes per-pairing generation selection, so `'require'` and `'disallow'` fail closed with `capability.unsupported` on BlueZ, WinRT, Android **and the deterministic `/testing` backend** rather than being silently ignored; the contract is in place for a backend that can honour it. The deterministic backend previously ignored the field and reported a Secure Connections bond under the exact option that forbids one, so a consumer's suite could pass against a contract every real radio rejects — the one way test infrastructure can actively mislead. A test that asserted a successful pair under `'require'` or `'disallow'` now sees `capability.unsupported`, which is what production would have done (#144, #143).
+
+### Documentation
+
+- Every hardcoded timing and capacity constant in `src/` is now classified as a protocol invariant, a safety bound, or host policy, and each one that stays fixed carries a comment at its definition saying why. Undocumented constants were the defect: a fixed deadline that is never explained reads as a device fault when a slower host misses it (#148).
+- `find()`'s 10 s fallback deadline and `adapter.waitUntilReady()`'s 10 s fallback deadline are named constants shared between the in-process and IPC managers, so the same logical operation cannot expire at two different times either side of the IPC boundary (#148).
 
 ## [4.0.5] - 2026-08-25
 

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-The current package is `4.0.5`. 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.
+The current package is `4.0.6`. 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

@@ -6,7 +6,7 @@
 
 It is an evolution of `react-native-ble-plx`, rewritten as a **cross-platform unified product**. One bytes-first BLE model and lifecycle semantics across hosts, with host-specific construction and ownership. The root package never picks a radio for you, and it will not quietly fall back to a simulator or a different backend.
 
-Install `unified-ble-manager` from npm (`4.0.5` on `latest`). The root import does not pick a radio. Package SemVer and backend support labels are independent: each radio backend stays Experimental until live-radio evidence says otherwise. See [`docs/PLATFORMS.md`](docs/PLATFORMS.md).
+Install `unified-ble-manager` from npm (`4.0.6` on `latest`). The root import does not pick a radio. Package SemVer and backend support labels are independent: each radio backend stays Experimental until live-radio evidence says otherwise. See [`docs/PLATFORMS.md`](docs/PLATFORMS.md).
 
 > Sponsored by [Imagi Explain](https://imagiexplain.com) — researched, narrated whiteboard explainers from a prompt, a PDF, or your notes.
 

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`, `4.0.1`, `4.0.2`, and `4.0.3` are immutable. `4.0.5` is the current train head.
+once tagged. Stable `4.0.0`, `4.0.1`, `4.0.2`, `4.0.3`, `4.0.4`, and `4.0.5` are immutable. `4.0.6` is the current train head.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -133,7 +133,7 @@ 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.5
+## Releasing 4.0.6
 
 The source version is prepared on `main` before the tag. The release workflow verifies that every initial release tag points at the exact current `main` commit before publication; do not create that tag from a side branch or an older commit. Do not retag immutable `v4.0.0`, `v4.0.1`, `v4.0.2`, or `v4.0.3`.
 
@@ -145,12 +145,12 @@ git checkout main
 git pull --ff-only origin main
 
 test "$(git branch --show-current)" = "main"
-test "$(node -p "require('./package.json').version")" = "4.0.5"
+test "$(node -p "require('./package.json').version")" = "4.0.6"
 git diff --exit-code
 git diff --cached --exit-code
 
-git tag -a v4.0.5 -m "v4.0.5"
-git push origin v4.0.5
+git tag -a v4.0.6 -m "v4.0.6"
+git push origin v4.0.6
 ```
 
 Do not push another commit to `main` between the final verification and the tag push.
@@ -178,26 +178,34 @@ Stable versions publish to `latest`. Active `4.0.0-rc.*` candidates also publish
 
 ## Post-release verification
 
-After the workflow succeeds:
+After the workflow succeeds, verify the registry rather than the workflow log:
+a green publish job and a package a consumer can actually install are not the
+same claim.
 
 ```sh
-release_candidate=4.0.0-rc.N
+version=4.0.6
 
-npm view "unified-ble-manager@$release_candidate" version
+npm view "unified-ble-manager@$version" version
 npm view unified-ble-manager dist-tags --json
-npm view "unified-ble-manager@$release_candidate" repository --json
-npm view "unified-ble-manager@$release_candidate" license
+npm view "unified-ble-manager@$version" repository --json
+npm view "unified-ble-manager@$version" license
+npm view "unified-ble-manager@$version" dist.integrity
 ```
 
 Then verify:
 
-- npm `latest` resolves to the selected release candidate;
+- npm `latest` resolves to the released version (a stable release moves
+  `latest`; a prerelease must leave it alone and publish to `next`);
 - the npm package page shows provenance for the published artifact;
-- the GitHub Release exists at the selected candidate tag and is marked prerelease;
-- its attached tarball/SBOM/license artifacts correspond to the release workflow output;
-- a clean consumer can install `unified-ble-manager` (no version pin) and import the documented host entrypoints.
-
-After the later stable tag, repeat the same checks for `4.0.0`. `latest` then moves to `4.0.0`.
+- the GitHub Release exists at that tag, and is marked prerelease only if the
+  version is one;
+- its attached tarball/SBOM/license artifacts correspond to the release
+  workflow output;
+- a clean consumer, in a directory outside this repository, can install
+  `unified-ble-manager` with no version pin and import the documented host
+  entrypoints. This is the check that catches a packaging gap the repository's
+  own tests cannot see: `@babel/runtime` shipped undeclared in 4.0.4 and only a
+  real external consumer surfaced it.
 
 ## Failed release or partial publish
 

package/SBOM.cdx.json

@@ -6,15 +6,15 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.5",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.6",
       "name": "unified-ble-manager",
-      "version": "4.0.5",
+      "version": "4.0.6",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.5"
+      "purl": "pkg:npm/unified-ble-manager@4.0.6"
     },
     "properties": [
       {
@@ -560,7 +560,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.5",
+      "ref": "pkg:npm/unified-ble-manager@4.0.6",
       "dependsOn": [
         "pkg:npm/%40babel/runtime@7.29.7",
         "pkg:npm/%40tauri-apps/api@2.11.1",

package/THIRD_PARTY_LICENSES.json

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

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/expo/UnifiedBleExpoRuntimeModule.java

@@ -247,13 +247,29 @@ public final class UnifiedBleExpoRuntimeModule extends NativeUnifiedBleExpoRunti
     }
   }
 
+  /**
+   * Read a manifest meta-data flag without assuming how the platform typed it.
+   *
+   * <p>The config plugin writes {@code android:value="true"}, but the Android manifest parser
+   * coerces the literals {@code "true"} and {@code "false"} into a {@link Boolean} before they
+   * reach the {@link Bundle}. Reading such an entry with {@code getString} logs a type warning and
+   * yields {@code null}, so the caller silently falls back to its default and every configuration
+   * digests identically - which defeats the purpose of a digest that exists to detect drift.
+   */
+  private static boolean metadataFlag(Bundle metadata, String key, boolean fallback) {
+    final Object value = metadata.get(key);
+    if (value instanceof Boolean) return (Boolean) value;
+    if (value instanceof String) return Boolean.parseBoolean((String) value);
+    return fallback;
+  }
+
   private String configurationDigest(String legacyLocationPolicy) {
     final Bundle metadata = applicationMetadata();
     final String canonical = "unified-ble-expo-runtime-v1\n"
         + "platform=android\n"
         + "legacyLocationPolicy=" + legacyLocationPolicy + "\n"
-        + "neverForLocation=" + metadata.getString(NEVER_FOR_LOCATION_METADATA, "false") + "\n"
-        + "requiredHardware=" + metadata.getString(REQUIRED_HARDWARE_METADATA, "false") + "\n";
+        + "neverForLocation=" + metadataFlag(metadata, NEVER_FOR_LOCATION_METADATA, false) + "\n"
+        + "requiredHardware=" + metadataFlag(metadata, REQUIRED_HARDWARE_METADATA, false) + "\n";
     try {
       final byte[] digest = MessageDigest.getInstance("SHA-256")
           .digest(canonical.getBytes(StandardCharsets.UTF_8));

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

@@ -6,6 +6,7 @@ import android.bluetooth.BluetoothGattCharacteristic
 import android.content.Context
 import android.os.Build
 import android.os.SystemClock
+import com.sfourdrinier.unifiedblemanager.protocol.generated.NATIVE_PROTOCOL_VERSION
 import com.sfourdrinier.unifiedblemanager.protocol.generated.RecordKind
 import com.sfourdrinier.unifiedblemanager.radio.OwnedAndroidGattRadio
 import com.sfourdrinier.unifiedblemanager.radio.OwnedRadioTeardownFailure
@@ -766,7 +767,7 @@ class UnifiedBleProtocolAndroidDispatcher(
   private fun emitSuccess(command: ProtocolWireRecord, kind: String, additions: Map<Int, ProtocolWireValue> = emptyMap()) {
     if (!isPending(command)) return
     val fields = mutableMapOf<Int, ProtocolWireValue>(
-      1 to ProtocolWireValue.UnsignedIntegerValue(1),
+      1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
       2 to ProtocolWireValue.StringValue(kind),
       3 to ProtocolWireValue.RecordValue(terminal(command, "succeeded"))
     )
@@ -798,7 +799,7 @@ class UnifiedBleProtocolAndroidDispatcher(
     val result = ProtocolWireRecord(
       RecordKind.RESULT,
       mapOf(
-        1 to ProtocolWireValue.UnsignedIntegerValue(1),
+        1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
         2 to ProtocolWireValue.StringValue(dispatcherResultKindFor(command.requiredString(3))),
         3 to ProtocolWireValue.RecordValue(terminal(command, "failed", code)),
         10 to ProtocolWireValue.RecordValue(error)
@@ -814,7 +815,7 @@ class UnifiedBleProtocolAndroidDispatcher(
     val result = ProtocolWireRecord(
       RecordKind.RESULT,
       mapOf(
-        1 to ProtocolWireValue.UnsignedIntegerValue(1),
+        1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
         2 to ProtocolWireValue.StringValue("cancelled"),
         3 to ProtocolWireValue.RecordValue(terminal(command, "failed", "cancelled")),
         10 to ProtocolWireValue.RecordValue(
@@ -841,7 +842,7 @@ class UnifiedBleProtocolAndroidDispatcher(
     val result = ProtocolWireRecord(
       RecordKind.RESULT,
       mapOf(
-        1 to ProtocolWireValue.UnsignedIntegerValue(1),
+        1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
         2 to ProtocolWireValue.StringValue("cancelled"),
         3 to ProtocolWireValue.RecordValue(terminal(command, "succeeded")),
         8 to ProtocolWireValue.StringValue(state)
@@ -866,7 +867,7 @@ class UnifiedBleProtocolAndroidDispatcher(
     val event = ProtocolWireRecord(
       RecordKind.EVENT,
       mapOf(
-        1 to ProtocolWireValue.UnsignedIntegerValue(1),
+        1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
         2 to ProtocolWireValue.StringValue("native-security-state-${SystemClock.elapsedRealtimeNanos()}"),
         3 to ProtocolWireValue.StringValue("securityStateChanged"),
         4 to ProtocolWireValue.RecordValue(attachment),
@@ -1112,7 +1113,7 @@ internal fun connectionLostEvent(
   return ProtocolWireRecord(
     RecordKind.EVENT,
     mapOf(
-      1 to ProtocolWireValue.UnsignedIntegerValue(1),
+      1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
       2 to ProtocolWireValue.StringValue("native-connection-lost-$nativeHandle-$ingressOrdinal"),
       3 to ProtocolWireValue.StringValue("connectionLost"),
       4 to ProtocolWireValue.RecordValue(connection.requiredRecord(1)),
@@ -1134,7 +1135,7 @@ internal fun databaseChangedEvent(
   return ProtocolWireRecord(
     RecordKind.EVENT,
     mapOf(
-      1 to ProtocolWireValue.UnsignedIntegerValue(1),
+      1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
       2 to ProtocolWireValue.StringValue("native-database-changed-$nativeHandle-$ingressOrdinal"),
       3 to ProtocolWireValue.StringValue("databaseChanged"),
       4 to ProtocolWireValue.RecordValue(attachment),

package/android/src/main/jni/UnifiedBleProtocolJsiBinding.cpp

@@ -67,6 +67,10 @@ struct JsiEventSinkState final {
   protocol::AndroidIngressOrdinalAllocator ingressOrdinalAllocator{1U};
   protocol::AndroidJsiBinaryCleanupLedger binaryCleanupLedger{
       kMaximumBinaryCleanupReferences};
+  // A record the codec refuses never reaches JavaScript, so nothing downstream
+  // can count it. The tally lives here so the diagnostic that replaces the
+  // dropped record can say how many have been lost on this attachment.
+  std::atomic<std::uint64_t> quarantinedRecords{0U};
 };
 
 std::mutex eventSinkStatesMutex;
@@ -1339,6 +1343,30 @@ bool deliverNativeResult(
     const std::shared_ptr<protocol::NativeProtocolControlRuntime>& activeRuntime,
     const protocol::ProtocolRecord& result);
 
+bool deliverNativeEvent(
+    const std::shared_ptr<JsiEventSinkState>& state,
+    const std::shared_ptr<protocol::NativeProtocolControlRuntime>& activeRuntime,
+    const protocol::ProtocolRecord& event);
+
+protocol::ProtocolRecord diagnosticEvent(
+    jlong nativeHandle,
+    const std::shared_ptr<JsiEventSinkState>& state,
+    const std::shared_ptr<protocol::NativeProtocolControlRuntime>& activeRuntime,
+    const std::string& code,
+    const std::string& message);
+
+// Report a record the codec refused. The dropped record cannot be recovered --
+// it is malformed by definition -- but the application is entitled to learn
+// that the boundary discarded something it was asked to deliver, which a
+// logcat line alone does not tell it. The diagnostic is built natively, so it
+// carries a correct version stamp and survives the validation that the
+// quarantined record failed.
+void reportQuarantinedRecord(
+    jlong nativeHandle,
+    const std::shared_ptr<JsiEventSinkState>& state,
+    const std::shared_ptr<protocol::NativeProtocolControlRuntime>& activeRuntime,
+    const char* reason);
+
 bool emitRecordFromJava(JNIEnv* environment, jlong nativeHandle, jbyteArray encodedRecord) {
   if (encodedRecord == nullptr) {
     return false;
@@ -1403,6 +1431,7 @@ bool emitRecordFromJava(JNIEnv* environment, jlong nativeHandle, jbyteArray enco
         "UnifiedBleProtocol",
         "emitRecordNative quarantined invalid Android record: %s",
         error.what());
+    reportQuarantinedRecord(nativeHandle, state, activeRuntime, error.what());
     if (decodedRecord.has_value() && decodedRecord->kind == protocol::RecordKind::result) {
       requestFatalAttachment(
           state,
@@ -1412,6 +1441,43 @@ bool emitRecordFromJava(JNIEnv* environment, jlong nativeHandle, jbyteArray enco
   }
 }
 
+void reportQuarantinedRecord(
+    jlong nativeHandle,
+    const std::shared_ptr<JsiEventSinkState>& state,
+    const std::shared_ptr<protocol::NativeProtocolControlRuntime>& activeRuntime,
+    const char* reason) {
+  const auto quarantined = state->quarantinedRecords.fetch_add(1U) + 1U;
+  try {
+    if (!deliverNativeEvent(
+            state,
+            activeRuntime,
+            diagnosticEvent(
+                nativeHandle,
+                state,
+                activeRuntime,
+                "recordQuarantined",
+                std::string("Android record was quarantined and not delivered (") +
+                    std::to_string(quarantined) + " on this attachment): " +
+                    (reason == nullptr ? "unknown error" : reason)))) {
+      __android_log_print(
+          ANDROID_LOG_ERROR,
+          "UnifiedBleProtocol",
+          "Android quarantine diagnostic was rejected handle=%lld quarantined=%llu",
+          static_cast<long long>(nativeHandle),
+          static_cast<unsigned long long>(quarantined));
+    }
+  } catch (const std::exception& error) {
+    // The quarantine path is already the failure path; a diagnostic that cannot
+    // be built must not replace the original record's failure with its own.
+    __android_log_print(
+        ANDROID_LOG_ERROR,
+        "UnifiedBleProtocol",
+        "Android quarantine diagnostic could not be built handle=%lld: %s",
+        static_cast<long long>(nativeHandle),
+        error.what());
+  }
+}
+
 bool deliverNativeResult(
     const std::shared_ptr<JsiEventSinkState>& state,
     const std::shared_ptr<protocol::NativeProtocolControlRuntime>& activeRuntime,

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

@@ -231,6 +231,23 @@ class UnifiedBleProtocolAndroidFindingsTest {
     assertTrue(Regex("return device.getAddress\\(\\)").containsMatchIn(addressProjection))
   }
 
+  // Regression guard for issue #140: the dispatcher stamped a literal 1 on
+  // field 1 of every control-plane record while the codec required 2, so every
+  // result it emitted -- including the one describing a failed connect -- was
+  // quarantined by the native codec and never reached JavaScript. The stamp has
+  // to follow the generated schema, not a number typed next to the field id.
+  @Test
+  fun `dispatcher records stamp the generated protocol version`() {
+    val source = readAndroidSource(
+      "android/src/main/java/com/sfourdrinier/unifiedblemanager/protocol/UnifiedBleProtocolAndroidDispatcher.kt"
+    )
+
+    assertTrue(source.contains("import com.sfourdrinier.unifiedblemanager.protocol.generated.NATIVE_PROTOCOL_VERSION"))
+    val stamps = Regex("""\n\s*1 to ProtocolWireValue\.UnsignedIntegerValue\((.+)\),""").findAll(source).toList()
+    assertTrue(stamps.isNotEmpty())
+    assertTrue(stamps.all { it.groupValues[1] == "NATIVE_PROTOCOL_VERSION.toLong()" })
+  }
+
   private fun readAndroidSource(relativePath: String): String {
     val candidates = listOf(
       File(relativePath),

package/docs/ADR/2026-07-4.0-backend-contract.md

@@ -23,10 +23,22 @@ normative behavioral authority.
 ## Contract shape and version skew
 
 `BackendProvider` reports loadability, lists adapters, requires a stable
-host-scoped adapter selection where necessary, and creates one backend bound to
-that adapter. Loadability, adapter presence, adapter power, and authorization
-are different states. Selecting ambiguously fails `adapter.selection-required`
-or `adapter.ambiguous`; a provider never chooses a convenient default.
+host-scoped adapter selection, and creates one backend bound to that adapter.
+Loadability, adapter presence, adapter power, and authorization are different
+states. The low-level provider never silently substitutes a different adapter:
+a named selection that is absent or stale fails `adapter.unavailable`.
+
+Choosing a *default* adapter when the caller names none is an ergonomics
+concern that belongs one layer up, not in the provider. The Node convenience
+factories (`createBluezBleManager` and its siblings) select the first adapter,
+ordered deterministically by id, so the common single-adapter machine needs no
+configuration and a multi-adapter host still picks the same controller every
+run; a caller targets a specific controller by passing `adapterId`. This
+supersedes the earlier stance that ambiguous selection must fail: forcing every
+caller to name an adapter is poor ergonomics for the common case. The
+`adapter.selection-required` / `adapter.ambiguous` codes remain in the taxonomy
+for a provider that genuinely cannot pick, but the first-party host factories do
+not push that choice onto the caller.
 
 `BleCentralBackend` owns these required components:
 

package/docs/BONDING.md

@@ -42,14 +42,49 @@ replay an uncertain GATT write. Use the explicit `withRequiredSecurity` helper
 when the application wants a state check followed by an explicitly authorized
 pairing attempt and one callback invocation.
 
-Windows and BlueZ may expose system pairing and durable unpairing where their
-public APIs provide it. Android reports public bond-state transitions but does
+Windows and BlueZ expose system pairing and durable unpairing where their
+public APIs provide it.
+
+On BlueZ, `pair()` calls `org.bluez.Device1.Pair` and `unpair()` calls
+`org.bluez.Adapter1.RemoveDevice`; the library registers a just-works
+(`NoInputNoOutput`) `org.bluez.Agent1` on its own bus so the system-mediated
+ceremony can complete without an external agent. Just-works confirmation is
+auto-accepted; passkey and PIN *entry* ceremonies are rejected, matching the
+`NoInputNoOutput` capability. The agent is registered (not made the system
+default) so it applies to pairings this client initiates. This dispatch and
+agent policy are covered by unit tests, but their behavior against a live BlueZ
+daemon is a separate capability the first-party backend does not yet prove: the
+TCK marks `bluez:pairing-agent` unsupported for exactly that reason (a
+deterministic boundary cannot exercise a real SMP exchange), so treat live
+bonding as unverified until it is measured on real radio.
+
+Android reports public bond-state transitions but does
 not ship a reflection-based remove-bond operation. On the current Expo SDK 57 /
-Android API 36 artifact, the cancellation capability is also omitted because
-the public `cancelBondProcess` API is newer; an aborted or timed-out Android
-pair releases the library's pending-operation ownership but cannot cancel the
-OS ceremony; it may still reach a later bond terminal state, which `watch()`
-reports. Apple and Web keep generic
+Android API 36 artifact, native pairing cancellation is also unavailable because
+the public `cancelBondProcess` API is newer. When cancellation is unavailable
+the library cannot stop an in-flight OS ceremony, so rather than claim a cancel
+it did not perform, an aborted or timed-out `pair()` fails closed by rejecting
+with `capability.unsupported`; a bond may still reach a later terminal state,
+which `watch()` reports.
+
+This is a deliberate cross-backend difference callers should handle: where a
+backend can cancel an in-flight pairing (BlueZ, WinRT), an aborted or timed-out
+attempt resolves `{ outcome: 'cancelled' }`; where it cannot (an Android build
+without the cancellation extension), the attempt rejects with
+`capability.unsupported` instead of misreporting a cancellation that did not
+happen.
+
+There is a second, narrower window: an abort or deadline that lands after the
+bond has *already* completed but before `pair()` has returned. On BlueZ this is
+reported truthfully as `paired` (never `cancelled`), because the native pairing
+call resolves only on a completed bond. On Android and WinRT the public outcome
+is currently committed when the abort fires, before the native result is
+observed, so this race can surface `cancelled` for a peer that did in fact
+bond; the bond is still authoritative and visible through `watch()`/`state()`.
+Aligning Android and WinRT with BlueZ's report-the-bond behavior is tracked
+separately.
+
+Apple and Web keep generic
 pairing/bonding unsupported where their public APIs do not provide a truthful
 measurement; Web `forget()` remains origin-authorization revocation, not
 `unpair`.

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.
 
-The current package is `4.0.5`. The release ships Node-API v8 prebuilds covering macOS and Windows `arm64`/`x64` for both Node and modern Electron.
+The current package is `4.0.6`. The release ships 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 the published `4.0.5` package. Those options match
+Use the v2 plugin options in the published `4.0.6` package. Those options match
 the schema introduced at `4.0.0-rc.4`. Expo Go cannot load this native module.
 
 ## Installation and development build
@@ -15,7 +15,7 @@ the schema introduced at `4.0.0-rc.4`. Expo Go cannot load this native module.
 Pin the package so a later `latest` bump does not change native plugin options
 without a rebuild:
 
-    pnpm add unified-ble-manager@4.0.5
+    pnpm add unified-ble-manager@4.0.6
     pnpm add expo@^57.0.0 expo-dev-client
     npx expo prebuild --clean
     npx expo run:ios

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.
 
-`unified-ble-manager@4.0.5` is the published, immutable stable package/API. Immutable `4.0.0`, `4.0.1`, `4.0.2`, and `4.0.3` remain published history. Backend support labels remain
+`unified-ble-manager@4.0.6` is the published, immutable stable package/API. Immutable `4.0.0`, `4.0.1`, `4.0.2`, and `4.0.3` remain published history. Backend support labels remain
 evidence-derived. This package does not rewrite the evidence inventory: a backend remains at the support level
 justified by its records. The alpha train, including `v4.0.0-alpha.40`, remains historical implementation/release
 evidence and must not be used to claim a higher current support label than it actually proved.

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.
 
-The current package is `4.0.5`.
+The current package is `4.0.6`.
 
 ## Pick a host
 
@@ -27,7 +27,7 @@ The current package is `4.0.5`.
 Pin the current package for a known native rebuild:
 
 ```sh
-pnpm add unified-ble-manager@4.0.5
+pnpm add unified-ble-manager@4.0.6
 ```
 
 Declare Android Bluetooth permissions and the BLE hardware feature yourself,
@@ -37,10 +37,10 @@ request runtime permissions on Android 12+, add
 #### Expo / CNG v2
 
 The Expo v2 schema and `unified-ble-manager/expo` factory are in the published
-`4.0.5` package. Pin that exact version:
+`4.0.6` package. Pin that exact version:
 
 ```sh
-pnpm add unified-ble-manager@4.0.5
+pnpm add unified-ble-manager@4.0.6
 ```
 
 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) |
 
-The current package is `4.0.5`. The release ships 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.
+The current package is `4.0.6`. The release ships 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
 
@@ -22,7 +22,7 @@ import { createBluezBleManager } from 'unified-ble-manager/node/bluez'
 const manager = await createCoreBluetoothBleManager()
 ```
 
-If there is no adapter, the factory throws `adapter.unavailable`. If more than one adapter exists and you omit `adapterId`, it throws `adapter.ambiguous`. Missing native artifacts throw `capability.unavailable` — there is no fallback to Noble, Web Bluetooth, or a simulator. Expected Node engines are those in `package.json`.
+If there is no adapter, the factory throws `adapter.unavailable`. If more than one adapter exists and you omit `adapterId`, the factory picks the first adapter in a deterministic order (by adapter id) so the common single-adapter case needs no configuration and a multi-adapter host still selects the same controller every run; pass `adapterId` (e.g. a BlueZ path like `/org/bluez/hci1`) to target a specific controller — an unusual need, for example a second USB Bluetooth dongle used for debugging. Missing native artifacts throw `capability.unavailable` — there is no fallback to Noble, Web Bluetooth, or a simulator. Expected Node engines are those in `package.json`.
 
 On `SIGINT`/`SIGTERM`, await `manager.destroy()`. Then scan/connect/GATT with the same `BleManager` helpers as React Native.
 

package/docs/PLATFORMS.md

@@ -8,7 +8,7 @@ This page is an evidence index, not a static compatibility matrix. An applicatio
 
 ## Package stability and backend support are separate
 
-`unified-ble-manager@4.0.5` is the published **stable package/API** for the 4.x contract; it is immutable. Backend support labels remain evidence-derived and independent of this SemVer. Immutable `4.0.0`, `4.0.1`, `4.0.2`, and `4.0.3` remain published history.
+`unified-ble-manager@4.0.6` is the published **stable package/API** for the 4.x contract; it is immutable. Backend support labels remain evidence-derived and independent of this SemVer. Immutable `4.0.0`, `4.0.1`, `4.0.2`, and `4.0.3` remain published history.
 
 This package is the portable API/semantics freeze; it does **not** mean every first-party backend is
 automatically Preview, Supported, or Reliability-qualified.