- 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.