unified-ble-manager 4.0.5 → 4.0.7

package/CHANGELOG.md

@@ -2,7 +2,63 @@
 
 All notable changes to `unified-ble-manager` are documented here.
 
-## [Unreleased]
+## [4.0.7] - 2026-08-26
+
+### Changed behaviour
+
+- `cancelPairing()` reports what the cancellation **achieved**, not what it requested, and can no longer contradict the pairing it cancelled. Every backend answered `'cancelled'` unconditionally the moment the cancel was dispatched, so a cancellation that lost the race told the caller no bond exists while one did — and a caller who believes that never looks again. It now reads the in-flight pairing's own result rather than forming a second opinion, which is what makes the two calls incapable of disagreeing: there is one source of truth and the cancellation reads it. `SecurityCancelPairingResult` gains the words to say so — `'paired'` when the bond completed before the cancellation arrived, and `'rejected'` (carrying the peer's reason) when the peer refused, because claiming credit for stopping something that stopped itself is the same substitution with the arrow reversed. A pairing that *fails* is not given an invented outcome: `cancelPairing()` rejects with the error the pairing rejected with. `'paired'` deliberately matches `SecurityPairResult`'s `'paired'` — a bond exists as a result of this operation — and is not `'already-paired'`, which in that type means the peer was bonded *before* the call; one word, one meaning, in both types. Applies to BlueZ, Android, WinRT **and** the deterministic `/testing` backend, since a mock that answers differently from every real radio lets a consumer's suite pass against a contract no device honours. WinRT additionally short-circuited *upstream* of the shared mapper — when its dispatcher reported the operation already terminal, which is exactly the lost race, it answered `'not-pairing'`, contradicting its own `pair()` and making that word mean both "there was nothing to stop" and "it was already over" (#159).
+
+### Additions
+
+- **`PairOptions.secureConnections` can now actually select the LE pairing generation on BlueZ — behind a host-supplied privileged operation.** Some peripherals accept only LE Legacy and terminate the link on a Secure Connections pairing request; 4.0.6 gave the contract a way to say so but no backend that could honour it. `org.bluez.Adapter1` (BlueZ 5.85) exposes no Secure Connections property and `Device1.Pair` takes no parameters — the setting lives behind the kernel management socket's Set Secure Connections command, which requires **`CAP_NET_ADMIN`**.
+
+  This package never acquires that privilege: it opens no management socket, shells out to nothing, and does not assume it is root. A library that silently escalates hands an application capabilities its author did not choose and cannot audit. The **host** supplies the operation via `BluezBackendProviderOptions.pairingGeneration`, which makes the escalation visible in the application that opted into it. Omit it and `'require'`/`'disallow'` keep failing closed exactly as in 4.0.6 — the default posture is unchanged.
+
+  Three properties of the kernel setting a host must accept, documented in `docs/BONDING.md` rather than discovered: it is **adapter-wide**, not per-pairing, so every pairing on that controller uses the selected generation while it is held; it **outlives the process**, because the kernel keeps it until something sets it back; and a **failed restore never changes the pairing's outcome** — a bond that was created is reported as created, with the restore failure reported separately, because leaving a controller in LE Legacy and telling a caller they are not bonded are both serious and are different facts. Concurrent *directed* pairings on one adapter are serialised so they cannot corrupt each other's restore value; an undirected (`'prefer'`) pairing does not take that lock and uses whichever generation is held, which `docs/BONDING.md` states beside the option.
+
+  `security:pairing-generation` joins the capability catalog and is reported by the instantiated backend at runtime: `unsupported` with the platform reason when no operation was supplied, `limited` when one was — so two BlueZ backends on one machine legitimately answer differently. Evidence is deterministic tests only; this is **not** physical-radio proof, and the label says so (#144).
+
+### Fixes
+
+- A Tauri connect that succeeds physically but is then denied admission no longer strands the peer. Both compensation branches — the caller vanished, and the caller's lease went stale — removed the peer reservation *before* attempting the disconnect and then discarded its result with `.ok()`. If that disconnect failed or hung while the peripheral stayed connected, the result was a connected peer with no owner and no handle: nothing could reach it, nothing could retry it, and the caller was told only that admission was denied. Compensation now follows the rule the explicit disconnect already follows — a bounded wait, a fresh state reading, and a D-Bus error naming a vanished device object read as evidence of release rather than as a failed question — and surrenders the reservation only when the platform proves the link is down. Genuine indeterminacy keeps it so a retry can reclaim the peer, and the admission error carries what compensation could not undo, which is the difference between "try again" and "a peer is stranded" (#146).
+
+### Known limitations
+
+- `pair()`'s abort path still reports `'cancelled'` without knowing whether the daemon bonded anyway. Learning the truth means waiting for the radio, and waiting risks a hang that a wedged daemon would inflict on the caller — which the suite explicitly forbids. Resolving it needs a vocabulary that can express "cancellation requested, bond state not yet known"; `state()` and `watch()` remain authoritative meanwhile (#157).
+
+## [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.7`. 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.7` 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`, `4.0.5`, and `4.0.6` are immutable. `4.0.7` is the current train head.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -133,7 +133,38 @@ 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.7
+
+Same shape as 4.0.6. The release workflow verifies that the tag points at the
+exact current `main` commit before publication; do not create it from a side
+branch or an older commit. Do not retag any immutable version.
+
+```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.7"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.7 -m "v4.0.7"
+git push origin v4.0.7
+```
+
+Do not push another commit to `main` between the final verification and the tag
+push.
+
+Before tagging, confirm the release-notes extraction finds the entry — the
+workflow's awk matches `^## \[4.0.7\]`, and a heading left as `[Unreleased]`
+publishes a stub instead of the changelog:
+
+```sh
+awk -v ver=4.0.7 '$0 ~ ("^## \\[" ver "\\]") {p=1;next} p && $0 ~ /^## \[/ {exit} p {print}' CHANGELOG.md
+```
+
+## 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 +176,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 +209,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.7",
       "name": "unified-ble-manager",
-      "version": "4.0.5",
+      "version": "4.0.7",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.5"
+      "purl": "pkg:npm/unified-ble-manager@4.0.7"
     },
     "properties": [
       {
@@ -560,7 +560,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.5",
+      "ref": "pkg:npm/unified-ble-manager@4.0.7",
       "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.7"
   },
   "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: