Replace HeadsetHold inference with route-heard ownership #59

Merged
alexander merged 26 commits from mcp/issue-11-route-heard-ownership into main 2026-09-19 14:57:05 +02:00
Owner

Closes #11.

Old ownership model

Routing continuity was inferred across several pieces of state: heardAudio, HeadsetHold.remembered, releasedToCar, framework isActive observations, and AudioOutputRoles.startTarget(). Different output-selection callers could therefore retire or resurrect that state differently, and system-policy route enumeration could compete with explicit listener intent.

New ownership model

  • One service-owned RouteHeardOwnership holds the strongest trustworthy route evidence for the currently loaded book/session generation.
  • Book changes and queue-empty transitions invalidate old heard-route evidence.
  • Explicit BookWave output selections are sequenced separately from weaker Android route-policy observations and outrank them.
  • Policy reassertion on car arrival is deliberately not published as new listener intent.
  • Multiple active ambiguous classic-A2DP candidates do not become ownership by enumeration order.
  • getAudioDevicesForAttributes remains described as attributes/system-policy evidence, not proof of BookWave's exact AudioTrack sink.

Deleted inference state

The old HeadsetHold state machine, heardAudio, releasedToCar, and startTarget() inference path are removed rather than layered beside the new owner.

Regression coverage

Focused ownership tests cover:

  • headset actually heard -> car arrives;
  • headset merely connected -> car arrives;
  • headset heard -> explicit phone speaker -> car arrives;
  • explicit headset A while framework policy reports B;
  • Car -> immediate Headset before callbacks settle, including stale intent replay;
  • remembered headset disconnect;
  • book change / queue empty;
  • old-book evidence isolation;
  • later legitimate route supersession;
  • multiple classic-A2DP candidates and enumeration order;
  • classic A2DP remaining Ambiguous;
  • Automatic release not immediately resurrecting the released headset.

Existing output-role tests retain the settled ADR-0029 contract: Car means Automatic/platform routing and Headset targets only legitimate headset candidates.

Verification

  • Forgejo pull-request.yml run 112 (Actions run id 114) passed on exact head 5f0e9184fd96df0b9500ac74ceb4885a8cb7d187.
  • Mutation proof: on throwaway commit 11d3472e9f1ebf2e7e18548974b9c6e7570e1b76, headsetForCar was deliberately changed to treat any connected headset as heard. The ownership suite failed as required, including:
    • merely connected headset is never remembered as heard;
    • explicit phone-speaker supersession;
    • Automatic does not re-adopt the released headset;
    • old-book route evidence isolation;
    • queue-empty invalidation.
      The mutation run was cancelled after the proof and the branch was deleted.

Device evidence still required

JVM/CI coverage proves BookWave's ownership, generation and precedence rules. It does not prove Android's route-policy observation is the exact sink carrying BookWave's track. Physical headset + phone-speaker + Android Auto/head-unit acceptance remains required before that platform boundary is called fully accepted.

Explicit non-goal

This PR does not implement #36 automatic resume behavior. A car arriving may still leave playback paused; no new play/resume-on-car-connection path is introduced.

Closes #11. ## Old ownership model Routing continuity was inferred across several pieces of state: `heardAudio`, `HeadsetHold.remembered`, `releasedToCar`, framework `isActive` observations, and `AudioOutputRoles.startTarget()`. Different output-selection callers could therefore retire or resurrect that state differently, and system-policy route enumeration could compete with explicit listener intent. ## New ownership model - One service-owned `RouteHeardOwnership` holds the strongest trustworthy route evidence for the currently loaded book/session generation. - Book changes and queue-empty transitions invalidate old heard-route evidence. - Explicit BookWave output selections are sequenced separately from weaker Android route-policy observations and outrank them. - Policy reassertion on car arrival is deliberately not published as new listener intent. - Multiple active ambiguous classic-A2DP candidates do not become ownership by enumeration order. - `getAudioDevicesForAttributes` remains described as attributes/system-policy evidence, not proof of BookWave's exact AudioTrack sink. ## Deleted inference state The old `HeadsetHold` state machine, `heardAudio`, `releasedToCar`, and `startTarget()` inference path are removed rather than layered beside the new owner. ## Regression coverage Focused ownership tests cover: - headset actually heard -> car arrives; - headset merely connected -> car arrives; - headset heard -> explicit phone speaker -> car arrives; - explicit headset A while framework policy reports B; - Car -> immediate Headset before callbacks settle, including stale intent replay; - remembered headset disconnect; - book change / queue empty; - old-book evidence isolation; - later legitimate route supersession; - multiple classic-A2DP candidates and enumeration order; - classic A2DP remaining `Ambiguous`; - Automatic release not immediately resurrecting the released headset. Existing output-role tests retain the settled ADR-0029 contract: Car means Automatic/platform routing and Headset targets only legitimate headset candidates. ## Verification - Forgejo `pull-request.yml` run 112 (Actions run id 114) passed on exact head `5f0e9184fd96df0b9500ac74ceb4885a8cb7d187`. - Mutation proof: on throwaway commit `11d3472e9f1ebf2e7e18548974b9c6e7570e1b76`, `headsetForCar` was deliberately changed to treat any connected headset as heard. The ownership suite failed as required, including: - merely connected headset is never remembered as heard; - explicit phone-speaker supersession; - Automatic does not re-adopt the released headset; - old-book route evidence isolation; - queue-empty invalidation. The mutation run was cancelled after the proof and the branch was deleted. ## Device evidence still required JVM/CI coverage proves BookWave's ownership, generation and precedence rules. It does not prove Android's route-policy observation is the exact sink carrying BookWave's track. Physical headset + phone-speaker + Android Auto/head-unit acceptance remains required before that platform boundary is called fully accepted. ## Explicit non-goal This PR does **not** implement #36 automatic resume behavior. A car arriving may still leave playback paused; no new play/resume-on-car-connection path is introduced.
alexander deleted branch mcp/issue-11-route-heard-ownership 2026-09-19 14:57:05 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude!59
No description provided.