pluriwave/openspec/changes/archive/2026-07-20-android-auto-local-music-phase3/archive-report.md

Archive Report: android-auto-local-music-phase3

Archived: 2026-07-20 (completion of entire 3-phase local-music feature)

Change Status: CLOSED — Verified PASS WITH WARNINGS, committed to main (git commit dfd40ca), implementation complete.

Executive Summary

Phase 3 of the local-music-in-Android-Auto feature — folder-scoped queue playback with shuffle and transport control wiring — is COMPLETE, verified, and archived. This change completes the entire planned 3-phase local-music feature. No further phases are planned. All 4 archived changes (Phase 1 + Paging Fast-Follow + Phase 2 + Phase 3, all dated 2026-07-19 and 2026-07-20) are now closed; the feature is ready for pre-release gate validation and eventual production release.

Phase 3 Implementation Outcome

Status

• Verification Verdict: PASS WITH WARNINGS (0 CRITICAL issues, 3 WARNINGS, 1 SUGGESTION)
• Test Results: 181/181 tests passed (0 failures)
• Regression Gate: 4 pre-existing radio/reconnect test suites (21 total tests) BYTE-FOR-BYTE UNTOUCHED — identical pass counts (8/5/3/5 = 21) before and after, zero regression
• Commit: dfd40ca on main, tagged [size:exception] per user's explicit informed choice (highest-risk change of session)
• Delivered: Single PR, ~1400+ lines (prod 470, tests 950)

Key Achievement — Regression Isolation Proven

The highest-risk aspect of this change — modifying PluriWaveAudioHandler's event listeners and adding a queue auto-advance mechanism alongside a live-stream reconnection state machine — was isolated via a strict mode boundary (_colaLocal != null is the ONLY gate). The proof:

1. Static proof: git diff --stat shows ZERO lines changed in _cambiarFuente, ControladorReconexion usage, _esErrorDeRed, _gestionarErrorReproduccion, _intentarReconexion, _reintentarFuente.
2. Test proof: The 4 protected regression test suites (servicio_audio_reconnect_test.dart, servicio_audio_session_test.dart, servicio_audio_source_switch_test.dart, servicio_audio_eq_reapply_test.dart) are BYTE-FOR-BYTE UNTOUCHED — not merely "same pass count", but identical file contents and identical test results.
3. Functional proof: playMediaItem, the public entry point for all external play actions (radio stations, groups, single tracks), unconditionally clears _colaLocal = null; _avanzandoCola = false FIRST before any handler mutation, guaranteeing zero queue leakage into radio playback.

This is the single strongest assurance available in this environment (static-review-only, no DHU/on-device testing) that radio playback is provably untouched.

Feature Completion — All 3 Phases Archived

Timeline of Archived Changes

1. Phase 1 (2026-07-19): SAF folder pick, lazy per-level traversal, placeholder art, single-track browse + play
2. Paging Fast-Follow (2026-07-19): On-demand pagination (replacing 50-item silent truncation)
3. Phase 2 (2026-07-19): Embedded metadata, LRU cache, quality sort, name buckets, album art
4. Phase 3 (2026-07-20): Folder-scoped queue, sequential/shuffled play, auto-advance, transport skip, mode isolation

Result: The local-music-in-Android-Auto feature is FEATURE-COMPLETE. Drivers can:

• Browse a local folder hierarchy in the car
• See real track metadata (title, album art) via embedded extraction
• Sort/filter tracks by name and quality
• Play a folder's tracks sequentially or shuffled
• Use car next/previous controls to navigate the queue
• Auto-switch between local queue and live radio with clean mode transitions

Out of scope by design (not promised, explicitly deferred):

• Recursive whole-subtree queueing (direct children only per folder)
• OS shuffle toggle (browsable action only, not AudioService.setShuffleMode)
• Repeat modes, persisted/resumable queues, queue-reordering UI

Standing Pre-Release Gate — On-Device / DHU Validation Required

CRITICAL STANDING RISK applying to ALL FOUR archived changes:

None of the native Android Auto surfaces built in this session have been runtime-verified on a real Android Auto head unit or Desktop Head Unit (DHU). All of it is static-review-only or unit-tested-via-extraction:

1. SAF folder picking (Phase 1): SAF API usage, permission persistence, DocumentFile traversal — no runtime test
2. Native metadata extraction (Phase 2): MediaMetadataRetriever.getMetadata(), readAudioMetadataBatch — extraction logic unit-tested locally, but device behavior untested
3. FileProvider art cache (Phase 2): Static cache file serving, no device test
4. Queue/shuffle handler wiring + transport controls (Phase 3): ProcessingState.completed firing, car next/previous button presses, queue advance behavior — static-review-only, no device test

Pre-release sign-off MUST include:

• Dedicated on-device QA pass on a real head unit or DHU
• Validation of all four surfaces (SAF pick, metadata display, album art, queue advance/skip)
• End-to-end testing of: single-track play, folder sequential play, folder shuffled play, auto-advance to next track, skip via car controls, radio-to-queue and queue-to-radio mode transitions
• Confirmation that no regressions to radio playback, reconnect, or EQ signal chain occur

This is non-negotiable before production release. The environment constraint (no DHU/on-device testing available during SDD execution) is documented and accepted; the risk is real and does not diminish with code review alone.

Artifacts Merged into Base Specification

The base Android Auto Media specification (openspec/specs/android-auto-media/spec.md) now includes 6 new requirements from Phase 3's delta spec:

1. Folder-Scoped Sequential Play Action — "Reproducir carpeta" prepended on page 0 of folders with audio files
2. Folder-Scoped Shuffled Play Action — "Reproducir aleatorio" alongside sequential, deterministically seeded
3. Local Queue Auto-Advance and Transport Skip — handler auto-advances on track completion, skipToNext/skipToPrevious move within queue
4. Local Queue Mode Isolation From Radio Playback (Regression Guard — CRITICAL) — _colaLocal nullability is the sole gate; mode boundaries prevent leakage
5. Local Queue End-of-Queue Behavior — clean stop with no wraparound on last track
6. New Action Media-IDs Are Collision-Free — carpeta_local_reproducir: and carpeta_local_aleatorio: collision-proven against all 8 existing prefixes

Change Artifacts

Artifact	Location	Notes
Proposal	archive/2026-07-20-android-auto-local-music-phase3/proposal.md	Honest scope reconciliation, single queue foundation feature, rationale for avoiding ConcatenatingAudioSource
Design	archive/2026-07-20-android-auto-local-music-phase3/design.md	6 ADRs, mode isolation via _colaLocal nullability, Fisher-Yates shuffle, file changes
Tasks	archive/2026-07-20-android-auto-local-music-phase3/tasks.md	26-item executable checklist (24 completed, 6.1 manual follow-up, 6.2 N/A), phases 0-5
Apply Progress	archive/2026-07-20-android-auto-local-music-phase3/apply-progress.md	181/181 tests passed, 4 protected suites byte-identical, 4 deviations disclosed, risks for verify phase
Verify Report	archive/2026-07-20-android-auto-local-music-phase3/verify-report.md	Verdict PASS WITH WARNINGS, priority investigations confirmed, 3 WARNINGs (static-review-only handler wiring, flutter analyze deferred, single-PR size:exception, DHU validation gate), 1 SUGGESTION (const list)
Base Spec (merged)	openspec/specs/android-auto-media/spec.md	6 new requirements appended; feature-complete specification

Test Coverage & Regression Data

New Tests (181 total passing)

• cola_local_test.dart (18 tests): ColaLocal navigation, decidirAvanceCola state machine, identical() guard for race condition
• navegacion_auto_test.dart (139 tests, was ~120): Fisher-Yates determinism, collision-freedom exhaustive, page-0 action prepend, 4 pre-existing assertions updated for new behavior
• controlador_reconexion_local_test.dart (3 tests, new): Bounded retry (5 failures → agotado, no 6th retry, no hang) with default maxReintentos:5, separate from protected suite to preserve byte-identical pass count

Protected Regression Suites (21 tests, ZERO regression)

• servicio_audio_reconnect_test.dart: 8 / 8 passing (UNCHANGED)
• servicio_audio_session_test.dart: 5 / 5 passing (UNCHANGED)
• servicio_audio_source_switch_test.dart: 3 / 3 passing (UNCHANGED)
• servicio_audio_eq_reapply_test.dart: 5 / 5 passing (UNCHANGED)

Baseline (Phase 0.1): 21 total, 0 failures
Final (Phase 5.4): 21 total, 0 failures
Diff on protected files: Zero lines changed (verified via git diff --stat)

Code Changes Summary

New Files

• lib/servicios/cola_local.dart (103 lines): Pure Dart queue holder, decision logic, identical() race guard
• test/servicios/cola_local_test.dart (181 lines): Full unit coverage of ColaLocal and decidirAvanceCola
• test/servicios/controlador_reconexion_local_test.dart (151 lines): Open-question regression test, bounded retry proof

Modified Files

• lib/servicios/navegacion_auto.dart (~180 lines added): Two new prefixes, Fisher-Yates, page-0 action prepend, queue orchestration
• lib/servicios/servicio_audio.dart (~190 lines added/changed): Queue state fields, playMediaItem split, auto-advance wiring, skip overrides, control gating
• openspec/specs/android-auto-media/spec.md: 6 new requirements appended (delta merged)

Total Impact

~1400+ lines delivered as single PR with user's explicit informed choice (highest-risk change of session, offered chain option, user chose single-PR anyway).

Deviations from Design (All Disclosed & Justified)

1. avanceEsValido folding: Guard placed inside _reproducirEntradaCola as optional parameter instead of external gate; functionally identical, avoids redundant URI resolve
2. Resolve-failure defense: Auto-advance that hits dead local file deactivates + stops (not left with stuck latch); defensive, consistent with ADR-4's no-inconsistent-state principle
3. androidCompactActionIndices dynamic: Compact-view play/pause index shifts from [0] to [1] when queue active (skip-previous prepended); necessary for correctness, negligible perf cost
4. Test placement: Open-question regression (5-failures-default-maxReintentos:5) placed in new file to preserve protected suite's byte-identical pass count

Issues & Risks

CRITICAL

• None in this change alone; however, see standing pre-release gate below

WARNINGS (3)

1. Handler wiring static-review-only: ProcessingState.completed, car transport buttons, race-guard runtime behavior never executed in unit tests (environment constraint — no DHU/on-device testing). Risk mitigated by (a) pure cola_local.dart fully unit-tested, (b) careful manual diff review, confirmed by verify phase. Requires on-device QA before release.
2. flutter analyze/coverage/gen-l10n deferred: Phase 6.1 explicitly out of scope (strict-TDD, only target test files run). Must run manually before merge.
3. Single-PR delivery size:exception: ~1400+ lines over estimated 850-950. User was informed this was highest-risk change of day and offered chain option; chose single-PR anyway. Review workload note for PR reviewers.

STANDING PRE-RELEASE GATE (APPLIES TO ALL 4 ARCHIVED PHASES)

• On-device / DHU validation of ALL native surfaces: SAF folder pick, MediaMetadataRetriever extraction, FileProvider art cache, queue/shuffle handler + car transport. Mandatory before production release — none runtime-tested; all static-review-only or unit-tested-locally.

Skill Compliance

• ✓ literal-encoding scan: 0 corruption matches in all touched/new .dart files
• ✓ work-unit-commits: No commits by apply/verify agents; orchestrator handles final commit/tag

Deferred / Out of Scope (Accepted)

• Phase 6.1: flutter analyze, flutter test --coverage, flutter gen-l10n — manual follow-up
• On-device / DHU QA — scheduled separately as standing pre-release gate
• Recursive subtree queueing — explicitly out of scope by design
• OS shuffle toggle — browsable action only
• Repeat modes, persisted queues, queue-reordering UI — not promised

Traceability: All SDD Artifacts

Phase	Artifact	Topic Key	Observation ID
Proposal	sdd/android-auto-local-music-phase3/proposal	—	(captured in engram)
Spec	sdd/android-auto-local-music-phase3/spec	—	(captured in engram)
Design	sdd/android-auto-local-music-phase3/design	—	(captured in engram)
Tasks	sdd/android-auto-local-music-phase3/tasks	—	(captured in engram)
Apply Progress	sdd/android-auto-local-music-phase3/apply-progress	—	(captured in engram)
Verify Report	sdd/android-auto-local-music-phase3/verify-report	—	(captured in engram)
Archive Report	sdd/android-auto-local-music-phase3/archive-report	—	(this document, saved to engram)

Closure

Change is CLOSED and ARCHIVED.

The entire 3-phase local-music-in-Android-Auto feature is now feature-complete, verified, and ready for:

1. Pre-release gate: On-device/DHU validation (mandatory, covers all 4 archived phases)
2. Production release: Once pre-release QA confirms all native surfaces on a real head unit

No further work on the local-music feature is planned. Subsequent PRs, if any, will be bug fixes or targeted enhancements (out of scope for SDD).