unified-ble-manager 4.0.25 → 4.0.26

package/CHANGELOG.md

@@ -6,6 +6,26 @@ All notable changes to `unified-ble-manager` are documented here.
 
 No changes yet.
 
+## [4.0.26] - 2026-09-06
+
+### Fixes
+
+- A third-party backend can now follow, and pass, the cancellation contract
+  4.0.7 introduced. `cancelOutcomeForPairResult` was exported from
+  `backend-contract/security` but re-exported type-only from the barrel, so it
+  never reached `/backend-sdk`; first-party backends imported it by deep
+  relative path and nothing failed. The TCK still hard-required
+  `outcome === 'cancelled'` from both `pair()` and `cancelPairing()`, so a
+  backend that correctly reported `'paired'` when the bond won the race failed
+  `security-pairing-cancellation-cleans-up` while conforming. The scenario now
+  asserts that the two calls do not contradict each other about one pairing,
+  checked through the shared mapper rather than against a fixed word.
+  `cancelOutcomeForPairResult` also gains a `default` branch so an out-of-contract
+  outcome from a third-party backend is named as `protocol.violation` instead of
+  surfacing as `undefined` and a raw TypeError several frames away. The `default`
+  routes through a `never` parameter, so a new first-party `SecurityPairResult`
+  variant is still a compile error (#167).
+
 ## [4.0.25] - 2026-09-05
 
 ### Fixes

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-This source targets `4.0.25`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
+This source targets `4.0.26`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
 
 This page is for a React Native app that already uses `react-native-ble-plx`. Web, Electron, Node, and Tauri are new hosts — use those pages after you understand the RN rewrite.
 

package/README.md

@@ -18,7 +18,7 @@ root import does not pick a radio. Package SemVer and backend support labels are
 independent: each radio backend keeps its evidence-derived label. See
 [`docs/PLATFORMS.md`](docs/PLATFORMS.md).
 
-This source tree is versioned `4.0.25`. Install the exact version shown in the npm
+This source tree is versioned `4.0.26`. Install the exact version shown in the npm
 registry. During release preparation, the version in `package.json` can be ahead
 of npm until the matching tag-driven workflow publishes it; the registry and
 GitHub release remain authoritative.

package/RELEASE.md

@@ -83,8 +83,8 @@ On release day, set `release_candidate` to the exact candidate required by the
 release plan. RC2, RC3, RC4, `4.0.0-rc.4.1`, and RC5 are already immutable
 once tagged. Stable `4.0.0` through `4.0.20` are immutable. The unpublished
 `v4.0.21` tag is also immutable after its cancelled workflow. `4.0.22`,
-`4.0.23`, and `4.0.24` are immutable tagged history. This branch prepares
-`4.0.25`.
+`4.0.23`, `4.0.24`, and `4.0.25` are immutable tagged history. This branch
+prepares `4.0.26`.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -112,6 +112,14 @@ The first stable tag `v4.0.0` is immutable published history. Do not recreate or
 git tag -a v4.0.0 -m "v4.0.0"
 ```
 
+## Releasing 4.0.26
+
+Release `v4.0.26` only from the exact current `main` commit after its canonical
+CI succeeds. Verify `package.json` is `4.0.26`, the worktree is clean, and
+release-note extraction finds `## [4.0.26]`. Push a new annotated `v4.0.26`
+tag; never move the immutable `v4.0.25` tag. Follow the required local validation,
+publish workflow, and registry verification below.
+
 ## Releasing 4.0.25
 
 Release `v4.0.25` only from the exact current `main` commit after its canonical
@@ -500,7 +508,7 @@ a green publish job and a package a consumer can actually install are not the
 same claim.
 
 ```sh
-version=4.0.25
+version=4.0.26
 
 npm view "unified-ble-manager@$version" version
 npm view unified-ble-manager dist-tags --json

package/SBOM.cdx.json

@@ -6,15 +6,15 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.25",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.26",
       "name": "unified-ble-manager",
-      "version": "4.0.25",
+      "version": "4.0.26",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.25"
+      "purl": "pkg:npm/unified-ble-manager@4.0.26"
     },
     "properties": [
       {
@@ -537,7 +537,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.25",
+      "ref": "pkg:npm/unified-ble-manager@4.0.26",
       "dependsOn": [
         "pkg:npm/%40babel/runtime@7.29.7",
         "pkg:npm/node-addon-api@8.9.0",

package/THIRD_PARTY_LICENSES.json

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

package/docs/ELECTRON.md

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

package/docs/EXPO_PLUGIN.md

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

package/docs/GAPS.4.0.md

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

package/docs/GETTING_STARTED.md

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

package/docs/NODE.md

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

package/docs/WEB.md

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

package/docs/generated/PLATFORM_SUPPORT.md

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

package/lib/commonjs/backend-contract/index.js

@@ -99,6 +99,12 @@ Object.defineProperty(exports, "byteLimit", {
     return _primitives.byteLimit;
   }
 });
+Object.defineProperty(exports, "cancelOutcomeForPairResult", {
+  enumerable: true,
+  get: function () {
+    return _security.cancelOutcomeForPairResult;
+  }
+});
 Object.defineProperty(exports, "canonicalUuid", {
   enumerable: true,
   get: function () {
@@ -310,6 +316,7 @@ Object.defineProperty(exports, "versionRange", {
   }
 });
 var _backend = require("./backend.js");
+var _security = require("./security.js");
 var _peerReference = require("./peer-reference.js");
 var _capabilities = require("./capabilities.js");
 var _errors = require("./errors.js");

package/lib/commonjs/backend-contract/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_backend","require","_peerReference","_capabilities","_errors","_gatt","_identity","_ipc","_operations","_primitives","_recovery","_scanPlanning"],"sourceRoot":"../../../src","sources":["backend-contract/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,IAAAA,QAAA,GAAAC,OAAA;AAmBA,IAAAC,cAAA,GAAAD,OAAA;AAsBA,IAAAE,aAAA,GAAAF,OAAA;AAuBA,IAAAG,OAAA,GAAAH,OAAA;AAwBA,IAAAI,KAAA,GAAAJ,OAAA;AAyBA,IAAAK,SAAA,GAAAL,OAAA;AASA,IAAAM,IAAA,GAAAN,OAAA;AAyBA,IAAAO,WAAA,GAAAP,OAAA;AAwDA,IAAAQ,WAAA,GAAAR,OAAA;AAwCA,IAAAS,SAAA,GAAAT,OAAA;AAkBA,IAAAU,aAAA,GAAAV,OAAA","ignoreList":[]}
+{"version":3,"names":["_backend","require","_security","_peerReference","_capabilities","_errors","_gatt","_identity","_ipc","_operations","_primitives","_recovery","_scanPlanning"],"sourceRoot":"../../../src","sources":["backend-contract/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,IAAAA,QAAA,GAAAC,OAAA;AAmBA,IAAAC,SAAA,GAAAD,OAAA;AACA,IAAAE,cAAA,GAAAF,OAAA;AAsBA,IAAAG,aAAA,GAAAH,OAAA;AAuBA,IAAAI,OAAA,GAAAJ,OAAA;AAwBA,IAAAK,KAAA,GAAAL,OAAA;AAyBA,IAAAM,SAAA,GAAAN,OAAA;AASA,IAAAO,IAAA,GAAAP,OAAA;AAyBA,IAAAQ,WAAA,GAAAR,OAAA;AAwDA,IAAAS,WAAA,GAAAT,OAAA;AAwCA,IAAAU,SAAA,GAAAV,OAAA;AAkBA,IAAAW,aAAA,GAAAX,OAAA","ignoreList":[]}

package/lib/commonjs/backend-contract/security.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.cancelOutcomeForPairResult = cancelOutcomeForPairResult;
+var _errors = require("./errors.js");
 /**
  * What a cancellation actually achieved, not what it requested.
  *
@@ -55,6 +56,15 @@ function cancelOutcomeForPairResult(result) {
       return {
         outcome: 'cancelled'
       };
+    default:
+      return unreachableCancelPairOutcome(result);
   }
 }
+function unreachableCancelPairOutcome(_result) {
+  // Unreachable for a compliant backend. Typing `_result` as `never` keeps a
+  // new SecurityPairResult variant a compile error; types erase, so a
+  // third-party invented outcome still throws instead of returning `undefined`
+  // and a raw TypeError several frames away.
+  throw (0, _errors.contractError)('protocol.violation', 'core', 'security.cancel-pairing.outcome');
+}
 //# sourceMappingURL=security.js.map

package/lib/commonjs/backend-contract/security.js.map

@@ -1 +1 @@
-{"version":3,"names":["cancelOutcomeForPairResult","result","outcome","reason"],"sourceRoot":"../../../src","sources":["backend-contract/security.ts"],"mappings":";;;;;;AA6FA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,0BAA0BA,CAACC,MAA0B,EAA+B;EAClG,QAAQA,MAAM,CAACC,OAAO;IACpB;IACA;IACA,KAAK,QAAQ;IACb,KAAK,gBAAgB;IACrB,KAAK,UAAU;MACb,OAAO;QAAEA,OAAO,EAAE;MAAS,CAAC;IAC9B;IACA;IACA,KAAK,UAAU;MACb,OAAO;QAAEA,OAAO,EAAE,UAAU;QAAEC,MAAM,EAAEF,MAAM,CAACE;MAAO,CAAC;IACvD,KAAK,WAAW;MACd,OAAO;QAAED,OAAO,EAAE;MAAY,CAAC;EACnC;AACF","ignoreList":[]}
+{"version":3,"names":["_errors","require","cancelOutcomeForPairResult","result","outcome","reason","unreachableCancelPairOutcome","_result","contractError"],"sourceRoot":"../../../src","sources":["backend-contract/security.ts"],"mappings":";;;;;;AAAA,IAAAA,OAAA,GAAAC,OAAA;AA8FA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,0BAA0BA,CAACC,MAA0B,EAA+B;EAClG,QAAQA,MAAM,CAACC,OAAO;IACpB;IACA;IACA,KAAK,QAAQ;IACb,KAAK,gBAAgB;IACrB,KAAK,UAAU;MACb,OAAO;QAAEA,OAAO,EAAE;MAAS,CAAC;IAC9B;IACA;IACA,KAAK,UAAU;MACb,OAAO;QAAEA,OAAO,EAAE,UAAU;QAAEC,MAAM,EAAEF,MAAM,CAACE;MAAO,CAAC;IACvD,KAAK,WAAW;MACd,OAAO;QAAED,OAAO,EAAE;MAAY,CAAC;IACjC;MACE,OAAOE,4BAA4B,CAACH,MAAM,CAAC;EAC/C;AACF;AAEA,SAASG,4BAA4BA,CAACC,OAAc,EAAS;EAC3D;EACA;EACA;EACA;EACA,MAAM,IAAAC,qBAAa,EAAC,oBAAoB,EAAE,MAAM,EAAE,iCAAiC,CAAC;AACtF","ignoreList":[]}

package/lib/commonjs/implementation-version.js

@@ -7,5 +7,5 @@ exports.UNIFIED_BLE_IMPLEMENTATION_VERSION = void 0;
 // src/implementation-version.ts
 
 /** The one production version stamped into every first-party backend identity. */
-const UNIFIED_BLE_IMPLEMENTATION_VERSION = exports.UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.25';
+const UNIFIED_BLE_IMPLEMENTATION_VERSION = exports.UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.26';
 //# sourceMappingURL=implementation-version.js.map

package/lib/commonjs/tck/runner-public-scenarios.js

@@ -8,6 +8,7 @@ var _capabilities = require("../backend-contract/capabilities.js");
 var _connectionControls = require("../backend-contract/connection-controls.js");
 var _errors = require("../backend-contract/errors.js");
 var _primitives = require("../backend-contract/primitives.js");
+var _security = require("../backend-contract/security.js");
 var _bleManager = require("../manager/ble-manager.js");
 var _contracts = require("./contracts.js");
 var _runnerPublicScenarioSupport = require("./runner-public-scenario-support.js");
@@ -24,6 +25,20 @@ const publicScenarioId = 'manager.scan-connect-discover-read-notify-destroy';
 const publicScenarioFact = 'scan-connect-discover-read-notify-destroy-completes';
 const publicScenarioDefinitionId = 'scenario.scan-connect-discover-read-notify-destroy';
 
+/**
+ * A conformant backend agrees with itself about one pairing.
+ *
+ * This used to require `'cancelled'` from both calls, which made the suite
+ * penalise a backend for being correct: when the bond wins the race, the
+ * contract requires `pair()` to report `paired` and `cancelPairing()` to
+ * report `paired` - and the old assertion failed exactly that. What matters is
+ * not which word appears but that the two calls do not contradict each other,
+ * so the check is the shared mapper the contract is defined by.
+ */
+function cancellationIsConsistent(cancelled, cancelledPair) {
+  return (0, _security.cancelOutcomeForPairResult)(cancelledPair).outcome === cancelled.outcome;
+}
+
 /**
  * Executes the public manager vertical slice over the exact backend owned by
  * this runner fixture. Facts are emitted only after every public operation and
@@ -267,7 +282,7 @@ async function executeSecurityScenario(manager, fixture) {
   }), (0, _runnerPublicScenarioSupport.fact)('security-custom-challenge-is-bounded', !customCeremonySupported || custom.outcome === 'already-paired' || custom.outcome === 'paired', {
     outcome: custom.outcome,
     supported: customCeremonySupported
-  }), (0, _runnerPublicScenarioSupport.fact)('security-pairing-cancellation-cleans-up', cancelled.outcome === 'cancelled' && cancelledPair.outcome === 'cancelled' && afterCancellation.outcome === 'not-pairing', {
+  }), (0, _runnerPublicScenarioSupport.fact)('security-pairing-cancellation-cleans-up', cancellationIsConsistent(cancelled, cancelledPair) && afterCancellation.outcome === 'not-pairing', {
     cancelled: cancelled.outcome,
     cancelledPair: cancelledPair.outcome,
     afterCancellation: afterCancellation.outcome,
@@ -336,7 +351,7 @@ async function executeSystemOnlySecurityScenario(manager, fixture, securityAdapt
   }), (0, _runnerPublicScenarioSupport.fact)('security-custom-challenge-is-bounded', true, {
     supported: false,
     reason: 'BlueZ Agent1 custom ceremony is intentionally unsupported in this slice'
-  }), (0, _runnerPublicScenarioSupport.fact)('security-pairing-cancellation-cleans-up', !supportsCancellation || cancelled?.outcome === 'cancelled' && cancelledPair?.outcome === 'cancelled' && afterCancellation?.outcome === 'not-pairing', {
+  }), (0, _runnerPublicScenarioSupport.fact)('security-pairing-cancellation-cleans-up', !supportsCancellation || cancelled !== null && cancelled !== undefined && cancelledPair !== null && cancelledPair !== undefined && cancellationIsConsistent(cancelled, cancelledPair) && afterCancellation?.outcome === 'not-pairing', {
     cancelled: cancelled?.outcome ?? null,
     cancelledPair: cancelledPair?.outcome ?? null,
     afterCancellation: afterCancellation?.outcome ?? null,