unified-ble-manager 4.0.4 → 4.0.6

package/CHANGELOG.md

@@ -2,7 +2,64 @@
 
 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
+
+First release cut against a live peripheral. Every fix below came from driving a real CGM from an Android phone and a Linux/BlueZ host, and several are defects no unit test had reason to catch. Does not retag `v4.0.4`.
+
+### Fixes
+
+- `readiness()` no longer reports a working radio as `unavailable` before the Android adapter publishes its authoritative state; a boundary that has not yet been told the radio's state is a pending condition, not an absent radio (#116, #128).
+- The direct-GATT backend is shared by CoreBluetooth and React Native Android, so its diagnostics now name the platform that is actually running — `[unified-ble:android-gatt.*]` rather than `[CoreBluetoothBackend.*]` — and its operation ids are `direct-gatt.*` instead of `corebluetooth.*`. Scan-stop cleanup timeouts carry the platform identity instead of `platform: null` (#117, #128, #132).
+- An address known out of band can now enter the system: `ScanClause.addresses` and `connect({ address })`, gated on the reported `peer:address-targeting` capability, with pending BlueZ semantics that complete whenever the peripheral next advertises, and Android `ScanFilter.setDeviceAddress`. Hosts that cannot express a radio address — CoreBluetooth, Web, and the IPC transport — report the capability unsupported and fail closed rather than advertising something they cannot honour (#118, #128, #131, #133).
+- `ScanOptions.platform` is honoured instead of unconditionally rejected, so consumers can select Android scan mode; peripherals that advertise infrequently are no longer effectively undiscoverable behind the platform default duty cycle. Gated on `scan:platform-options` in the public, core and IPC paths; `match-lost` and pre-26 `legacy: false` fail closed rather than silently doing something else (#120, #130).
+- BlueZ GATT works again: occurrences are decimal indices rather than D-Bus object paths, so `discover()` no longer fails with `protocol.violation: public-gatt.occurrence` on every device — a regression introduced when the public validator was tightened without migrating the backend. Two same-UUID services are now distinctly addressable, which neither the old leniency nor the strict check managed (#123, #129).
+- The BlueZ boundary decodes the `y` and `a{qv}` D-Bus variants that BlueZ 5.85 actually sends, and routes `Adapter1.ConnectDevice` through the boundary instead of rejecting it as locally unsupported; without these the backend could not attach at all (#128).
+- Public BLE resources are portable across copies, and closing an adapter watch's value stream tears the watch down instead of leaving a 25 ms poll timer and an abort listener alive (#122).
+- `@babel/runtime` is declared as a production dependency. The emitted CommonJS imports its helpers, so an external linked checkout failed with `MODULE_NOT_FOUND` while repository-local tests passed against a transitive copy — a packaging gap only a real consumer could surface (#134, #135).
+- A database stream is finalized after an invalidation retry succeeds, and per-subscription React cleanup and failed IPC CCCDs stay owned (#127).
+
+### Compatibility
+
+- Native protocol ABI 3 → 4. A JavaScript bundle carrying the new scan fields now fails attachment negotiation against an older native binary instead of failing at scan-start — or, worse, silently selecting the opposite scan mode.
+
+### Release integrity
+
+- Cut from the exact `main` merge commit through the tag-driven trusted-publishing workflow.
+- Intended for publication as `latest`; this does not promote backend support labels. The live-hardware runs behind these fixes are development evidence, not qualification evidence.
 
 ## [4.0.4] - 2026-08-25
 

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-The current package is `4.0.4`. 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.4` 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.4` 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.4
+## 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.4"
+test "$(node -p "require('./package.json').version")" = "4.0.6"
 git diff --exit-code
 git diff --cached --exit-code
 
-git tag -a v4.0.4 -m "v4.0.4"
-git push origin v4.0.4
+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,20 +6,20 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.4",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.6",
       "name": "unified-ble-manager",
-      "version": "4.0.4",
+      "version": "4.0.6",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.4"
+      "purl": "pkg:npm/unified-ble-manager@4.0.6"
     },
     "properties": [
       {
         "name": "unified-ble-manager:pnpm-lock-sha256",
-        "value": "95b40628ee5be6e80662325b6f7c09547541957e885f4bb714fe1aca28f4153f"
+        "value": "5fb778bd200cb93f552ec61264d53829dca5bdd27623ccc692d4d9bcbf9ec296"
       },
       {
         "name": "unified-ble-manager:dependency-scope",
@@ -28,6 +28,25 @@
     ]
   },
   "components": [
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/%40babel/runtime@7.29.7",
+      "group": "@babel",
+      "name": "runtime",
+      "version": "7.29.7",
+      "licenses": [
+        {
+          "expression": "MIT"
+        }
+      ],
+      "purl": "pkg:npm/%40babel/runtime@7.29.7",
+      "properties": [
+        {
+          "name": "unified-ble-manager:license-source",
+          "value": "package-metadata"
+        }
+      ]
+    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/%40isaacs/fs-minipass@4.0.1",
@@ -428,6 +447,10 @@
     }
   ],
   "dependencies": [
+    {
+      "ref": "pkg:npm/%40babel/runtime@7.29.7",
+      "dependsOn": []
+    },
     {
       "ref": "pkg:npm/%40isaacs/fs-minipass@4.0.1",
       "dependsOn": [
@@ -537,8 +560,9 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.4",
+      "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",
         "pkg:npm/node-addon-api@8.9.0",
         "pkg:npm/node-gyp@12.4.0"

package/THIRD_PARTY_LICENSES.json

@@ -4,12 +4,12 @@
   "schemaVersion": "1.0.0",
   "package": {
     "name": "unified-ble-manager",
-    "version": "4.0.4"
+    "version": "4.0.6"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",
     "lockfile": "pnpm-lock.yaml",
-    "lockfileSha256": "95b40628ee5be6e80662325b6f7c09547541957e885f4bb714fe1aca28f4153f"
+    "lockfileSha256": "5fb778bd200cb93f552ec61264d53829dca5bdd27623ccc692d4d9bcbf9ec296"
   },
   "reviewedOverrides": [
     {
@@ -27,6 +27,13 @@
   ],
   "unresolved": [],
   "packages": [
+    {
+      "name": "@babel/runtime",
+      "version": "7.29.7",
+      "license": "MIT",
+      "licenseSource": "package-metadata",
+      "purl": "pkg:npm/%40babel/runtime@7.29.7"
+    },
     {
       "name": "@isaacs/fs-minipass",
       "version": "4.0.1",

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
@@ -255,7 +256,8 @@ class UnifiedBleProtocolAndroidDispatcher(
         scanMode = options.requiredSignedInteger(3).toInt(),
         callbackType = options.requiredSignedInteger(4).toInt(),
         legacyScan = options.requiredBoolean(5),
-        allowDuplicates = options.requiredBoolean(2)
+        allowDuplicates = options.requiredBoolean(2),
+        deviceAddresses = options.optionalStringList(6).toTypedArray()
       )
       emitSuccess(command, "scanStarted")
     } catch (error: Exception) {
@@ -765,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"))
     )
@@ -797,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)
@@ -813,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(
@@ -840,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)
@@ -865,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),
@@ -1111,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)),
@@ -1133,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),
@@ -1180,6 +1182,11 @@ private fun ProtocolWireRecord.requiredStringList(fieldId: Int): List<String> {
   return if (value is ProtocolWireValue.StringListValue) value.value else throw IllegalArgumentException("String list field is missing")
 }
 
+private fun ProtocolWireRecord.optionalStringList(fieldId: Int): List<String> {
+  val value = fields[fieldId] ?: return emptyList()
+  return if (value is ProtocolWireValue.StringListValue) value.value else throw IllegalArgumentException("String list field is malformed")
+}
+
 private fun Boolean?.toNativeConnectableState(): Int = when (this) {
   true -> 1
   false -> 0

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

@@ -3,7 +3,7 @@
 package com.sfourdrinier.unifiedblemanager.protocol.generated
 
 const val NATIVE_PROTOCOL_VERSION: Int = 2
-const val NATIVE_PROTOCOL_ABI_VERSION: Int = 3
+const val NATIVE_PROTOCOL_ABI_VERSION: Int = 4
 const val NATIVE_PROTOCOL_CONTROL_SURFACE_VERSION: Int = 2
 const val MAXIMUM_CONTROL_RECORD_BYTES: Int = 262144
 const val MAXIMUM_BINARY_PAYLOAD_BYTES: Int = 524288
@@ -223,6 +223,7 @@ val NATIVE_PROTOCOL_FIELDS: List<FieldDescriptor> = listOf(
     FieldDescriptor(RecordKind.SCAN_OPTIONS, 3, "scanMode", "int64", true),
     FieldDescriptor(RecordKind.SCAN_OPTIONS, 4, "callbackType", "int64", true),
     FieldDescriptor(RecordKind.SCAN_OPTIONS, 5, "legacyScan", "boolean", true),
+    FieldDescriptor(RecordKind.SCAN_OPTIONS, 6, "deviceAddresses", "strings", false),
     FieldDescriptor(RecordKind.ADAPTER_STATE_SNAPSHOT, 1, "availability", "enum:adapterAvailability", true),
     FieldDescriptor(RecordKind.ADAPTER_STATE_SNAPSHOT, 2, "authorization", "enum:adapterAuthorization", true),
     FieldDescriptor(RecordKind.ADAPTER_STATE_SNAPSHOT, 3, "power", "enum:adapterPower", true),

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

@@ -394,8 +394,16 @@ class OwnedAndroidGattRadio(private val context: Context) {
     scanMode: Int,
     callbackType: Int = ScanSettings.CALLBACK_TYPE_ALL_MATCHES,
     legacyScan: Boolean = true,
-    allowDuplicates: Boolean = true
+    allowDuplicates: Boolean = true,
+    deviceAddresses: Array<out String> = emptyArray()
   ) {
+    // ScanSettings.Builder.setLegacy exists only on API 26+; below that the
+    // platform can only run a legacy scan, so accepting legacyScan=false would
+    // silently ignore the caller's extended-advertising request. Fail closed
+    // before any scan state is touched.
+    require(legacyScan || Build.VERSION.SDK_INT >= 26) {
+      "legacyScan=false requires ScanSettings.Builder.setLegacy (API 26+); this device cannot honour it"
+    }
     val normalizedServiceUuids = normalizeScanServiceUuids(serviceUuids?.toList() ?: emptyList())
     check(scanCallback == null) { "Android scan cleanup is still owned by a prior scan" }
     scanSeenDeviceIds.clear()
@@ -404,6 +412,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
     val builder = ScanSettings.Builder()
       .setScanMode(
         when (scanMode) {
+          -1 -> ScanSettings.SCAN_MODE_OPPORTUNISTIC
           0 -> ScanSettings.SCAN_MODE_LOW_POWER
           1 -> ScanSettings.SCAN_MODE_BALANCED
           2 -> ScanSettings.SCAN_MODE_LOW_LATENCY
@@ -417,8 +426,26 @@ class OwnedAndroidGattRadio(private val context: Context) {
     }
     val settings = builder.build()
     val filters = mutableListOf<ScanFilter>()
-    normalizedServiceUuids.forEach { uuid ->
-      filters.add(ScanFilter.Builder().setServiceUuid(ParcelUuid.fromString(uuid)).build())
+    val normalizedAddresses = deviceAddresses.map { it.uppercase() }.distinct()
+    if (normalizedAddresses.isEmpty()) {
+      normalizedServiceUuids.forEach { uuid ->
+        filters.add(ScanFilter.Builder().setServiceUuid(ParcelUuid.fromString(uuid)).build())
+      }
+    } else if (normalizedServiceUuids.isEmpty()) {
+      normalizedAddresses.forEach { address ->
+        filters.add(ScanFilter.Builder().setDeviceAddress(address).build())
+      }
+    } else {
+      normalizedAddresses.forEach { address ->
+        normalizedServiceUuids.forEach { uuid ->
+          filters.add(
+            ScanFilter.Builder()
+              .setDeviceAddress(address)
+              .setServiceUuid(ParcelUuid.fromString(uuid))
+              .build()
+          )
+        }
+      }
     }
     val cb = object : ScanCallback() {
       override fun onScanResult(callbackType: Int, result: AndroidScanResult) {

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: