ObliviOS Developer portal Project site

Home / Decisions / ADR-119

Land patch 0006 on the Bluetooth module: BluetoothDevice#setAirPodsMetadata.

Accepted, recorded 29 September 2026.

Decision
ADR-119
Date
2026-09-29
Status
AcceptedAccepted (uncompiled, see Consequences)
Part
AirPods
Mentions
ADR-117
Mentioned by
ADR-135

1Decision

Land patch 0006 on the Bluetooth module: BluetoothDevice#setAirPodsMetadata (@SystemApi) and IBluetooth#setAirPodsMetadata, gated by MANAGE_AIRPODS_IDENTITY, an 18-key allow-list, and a device that is bonded and registered through setAirPodsIdentity. Owner confirmed the ADR-117 O2 route on 2026-09-29.

2Why and evidence

Implements ADR-117 O2 exactly as recommended, so AirPodsApp never needs BLUETOOTH_PRIVILEGED.

Design points, each read from the pinned tree: the write reuses AdapterService#setMetadata and so the same storage and change-listener path; the platform already deletes a device's metadata on unbond (BluetoothStorageManager.kt:254-256, :862-866); the bond state is set (BondStateMachine.java:650) before AdapterService#handleBondStateChanged runs (:709), so the unbond hook sees a bond already gone.

The native registry has no getter, so the registered set is kept in Java (AirPodsIdentityTracker) under one lock shared by register, unbond and write, held across the storage write: a write cannot run after an unbond has completed, and a failure to clear native still drops the Java entry. Keys refused on purpose: ENHANCED_SETTINGS_UI_URI (makes Settings launch a URI), COMPANION_APP, DEVICE_TYPE, manufacturer, model and version.

The return value is true when the stored value already equals the request, so false always means refused or failed (the app uses that to notice a lost registration after a Bluetooth restart).

3Consequences

Landed on sovereignos-airpods-identity as e4b12de124 (git am exit 0; the ten touched files sha256-identical to the authoring worktree); package patch patches/packages-modules-bluetooth/0006 and SOURCE.md in sovereignos-platform aae5d04.

Evidence: 17 host tests over the two new classes pass, also when run against files fetched from the server tree; injecting the wrong key, dropping the bond check, and removing the lock each make the intended test fail (the first version of the lock test did not detect the removal and was replaced by a deterministic one); the setAirPodsMetadata declaration compiles with the tree's own aidl; all changed Java files parse.

Deadlock review (read, not run): the tracker lock is taken at exactly three sites (AdapterService.java setAirPodsIdentity, setAirPodsMetadata, the unbond hook); the storage write under it reaches onMetadataChanged, which only posts to the handler (:4729-4731), so nothing calls back into the tracker synchronously; the lock order is tracker then storage only, and the unbond hook takes the lock after mStorage.onBondStateChanged has returned.

Not proven: the Bluetooth module, AdapterService wiring, the whole IBluetooth.aidl (its include paths do not resolve outside the build, baseline included), the API file, and the three Kotlin binder tests were not compiled or run. If the Bluetooth process restarts, the native registry and the Java set both reset; the app must call setAirPodsIdentity(true) again and treats a false write as the signal. AIR-036 covers the hardware check.

4Review when

A rebase changing setMetadata, IBluetooth.aidl, BluetoothStorageManager unbond handling or the order of BondStateMachine lines 650 and 709; AIR-036 failing; any request to widen the key list (each key needs a named Settings reader).

Read from docs/governance/decision-log.md, entry ADR-119.