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

# Apply Progress: Android Auto Local Music — Phase 3 (Folder Queue + Shuffle)

## Status: DONE — all executable tasks complete in a single pass (single PR, `size:exception` per user's explicit choice)

Batch: FIRST and ONLY batch. All phases (0-5) implemented in one pass per
the user's explicit delivery-strategy choice (single PR with `size:exception`,
acknowledged as the highest-risk change of the session). Phase 6 items are
manual follow-up (not executable by this agent) or confirmed not applicable.

## Tasks completed: 24 / 26 executable checklist items (Phase 6.1 is
explicitly manual follow-up per tasks.md; Phase 6.2 confirmed not applicable,
no code change needed)

- Phase 0 (Regression Baseline): 0.1, 0.2 — DONE
- Phase 1 (Pure Foundations — ColaLocal/decidirAvanceCola/avanceEsValido): 1.1, 1.2, 1.3 — DONE
- Phase 2 (Shuffle & Collision): 2.1, 2.2, 2.3 — DONE
- Phase 3 (Handler Isolation Wiring, static-review-only): 3.1-3.8 — DONE
- Phase 4 (Browsable/Playable Actions): 4.1, 4.2, 4.3 — DONE
- Phase 5 (Open Question + Final Regression): 5.1-5.5 — DONE
- Phase 6 (Deviations/Manual Follow-up): 6.1 deferred (manual, `flutter analyze`/`--coverage`/`gen-l10n` not run per strict-TDD scope); 6.2 confirmed N/A (no native/manifest change)

## Files changed

### New
- `lib/servicios/cola_local.dart` — `ColaLocal` (immutable queue holder),
  `DecisionAvanceCola` enum, `decidirAvanceCola`, `avanceEsValido`. Pure
  Dart, no `just_audio` import, mirrors the `ControladorReconexion`
  extraction pattern so it is fully unit-testable without instantiating
  `PluriWaveAudioHandler`.
- `test/servicios/cola_local_test.dart` — 18 tests covering `ColaLocal`
  nav/boundaries, `decidirAvanceCola`'s 3-way gate, `avanceEsValido`'s
  `identical()` guard.
- `test/servicios/controlador_reconexion_local_test.dart` — 3 tests proving
  the design's open-question resolution: a dead local track retries up to
  the DEFAULT `maxReintentos: 5` via the existing `ControladorReconexion`
  (source-agnostic, no special-casing), fails cleanly on the 6th failure
  (no 6th retry, no hang, no crash). Deliberately kept as a SEPARATE file
  from `servicio_audio_reconnect_test.dart` so that protected suite's exact
  pass count stays byte-identical (see "Regression discipline" below).

### Modified
- `lib/servicios/navegacion_auto.dart` —
  - `pistasEnOrdenNombre`, `mezclarFisherYates`, `pistasEnOrdenAleatorio`
    (Fisher-Yates over the canonical name-sorted order, injected `Random`).
  - Two new `ConstructorArbolAuto` prefixes:
    `carpeta_local_reproducir:`/`carpeta_local_aleatorio:`, both
    PLAYABLE (unlike every other `carpeta_local_*` prefix), with
    predicates + strip-by-length codec, collision-proven at index 14
    against the 3 sibling `carpeta_local_*` prefixes and index 13 against
    `carpeta_local:`.
  - `itemsLocales`' page-0 prepend block extended: "Reproducir
    carpeta"/"Reproducir aleatorio" prepended BEFORE the sort/bucket nav
    entries (per Design ADR-5's explicit ordering), guarded by
    `totalPistas > 0` — absent for a folder with only subfolders.
  - `reproducirCarpetaLocal` (fetches children, filters/orders, calls
    `iniciarCola`; no-op on empty/unresolvable folder) and
    `construirMediaItemColaLocal` (resolves a queue track's content URI +
    MediaItem, reusing `reproducirPistaLocal`'s title derivation).
  - Test file `test/servicios/navegacion_auto_test.dart`: 139 tests total
    (was ~120 before this change) — added new groups for the above, PLUS
    updated 4 pre-existing tests whose exact item counts/positions shifted
    because the new page-0 prepend items are real production behavior
    changes (not a regression — this file is not one of the 4 protected
    suites):
    - "exactamente 50 items": `hasLength(51)` → `hasLength(53)`.
    - "51 a 100 items" pagina0: `hasLength(56)` → `hasLength(58)`.
    - "page-0 mode/bucket prepend" (>150-pistas case): first-5-non-playable
      loop replaced with explicit checks (index 0/1 = the two new playable
      action items, index 2-6 = calidad/buckets).
- `lib/servicios/servicio_audio.dart` (HIGHEST RISK, static-review-only —
  no handler instantiation possible in unit tests) —
  - New fields: `ColaLocal? _colaLocal`, `bool _avanzandoCola`.
  - `playMediaItem` split: public method now ALWAYS clears
    `_colaLocal`/`_avanzandoCola` FIRST, then delegates to new private
    `_encolarCambioFuente` (body is the previous `playMediaItem`
    implementation, byte-identical).
  - New `_reproducirEntradaCola(NodoLocal, {ColaLocal? colaEsperada})` —
    the ONLY other caller of `_encolarCambioFuente` besides public
    `playMediaItem`. `colaEsperada`, when provided, applies the
    `avanceEsValido` mid-await race guard AFTER resolving the content URI
    and BEFORE playing — functionally identical to the design's advance-flow
    pseudocode, refactored so the guard lives inside the sole resolve+play
    entry point (avoids a second, redundant URI resolve).
  - `_manejarFinPista(ProcessingState)` wired as the FIRST line of the
    `playerStateStream` listener, calling `decidirAvanceCola`; sets the
    `_avanzandoCola` latch synchronously before any await for the
    `avanzar` case; the radio `playing && ready` reset branch gained one
    additional line (`_avanzandoCola = false`) alongside its two existing
    untouched statements.
  - `_desactivarCola()`, `_iniciarColaLocal(List<NodoLocal>)` (the
    `iniciarCola` seam for `reproducirCarpetaLocal`).
  - `stop()` now also calls `_desactivarCola()` — `onTaskRemoved` inherits
    this for free (it calls `stop()`).
  - `skipToNext`/`skipToPrevious` overrides added: no-op when
    `_colaLocal == null`; `skipToNext` past the last track deactivates +
    stops (Design ADR-4, no wraparound); `skipToPrevious` at index 0
    clamps to 0 (restarts the track).
  - `playerStateStream`'s `playbackState.add(...)` gated: `controls`/
    `systemActions`/`androidCompactActionIndices` only add
    skip-previous/skip-next when `_colaLocal != null`; the `null` branch is
    byte-identical to the pre-change list (verified: same elements, same
    order, same compact index).
  - `playFromMediaId` gained a THIRD branch (after `eq_preset:`/`pista:`,
    before the station fallthrough) for the two new action prefixes,
    calling `reproducirCarpetaLocal` with `iniciarCola: _iniciarColaLocal`.
  - Confirmed UNTOUCHED by this change (verified via diff read): `_cambiarFuente`,
    `ControladorReconexion` usage/`_reconexion` field, `_esErrorDeRed`,
    `_gestionarErrorReproduccion`, `_intentarReconexion`, `_reintentarFuente`.
- `openspec/changes/android-auto-local-music-phase3/tasks.md` — all 24
  executable checklist items marked `[x]` with brief inline notes; 6.1 left
  unchecked (manual follow-up, explicitly out of this agent's scope).
- `openspec/changes/android-auto-local-music-phase3/design.md` — both Open
  Questions marked `[x]` confirmed, with the apply-time resolution recorded
  inline.

## Test results (independently re-confirmed via a single combined run)

Combined run of every touched/new test file
(`cola_local_test.dart` + `navegacion_auto_test.dart` +
`controlador_reconexion_local_test.dart` + the 4 protected regression
suites), `flutter test ... --concurrency=1 --timeout=60s`:

```
+181: All tests passed!
```

Per-file breakdown (from the same run, cumulative counters):
| File | Tests | Pass | Fail |
|---|---|---|---|
| `cola_local_test.dart` (new) | 18 | 18 | 0 |
| `navegacion_auto_test.dart` (modified) | 139 | 139 | 0 |
| `controlador_reconexion_local_test.dart` (new) | 3 | 3 | 0 |
| `servicio_audio_reconnect_test.dart` (protected) | 8 | 8 | 0 |
| `servicio_audio_session_test.dart` (protected) | 5 | 5 | 0 |
| `servicio_audio_source_switch_test.dart` (protected) | 3 | 3 | 0 |
| `servicio_audio_eq_reapply_test.dart` (protected) | 5 | 5 | 0 |
| **Total** | **181** | **181** | **0** |

## Regression discipline (Phase 0 baseline vs Phase 5.4 final — the
non-negotiable gate)

Baseline (Phase 0.1, captured BEFORE any code change):
`servicio_audio_reconnect_test.dart` = 8, `servicio_audio_session_test.dart`
= 5, `servicio_audio_source_switch_test.dart` = 3,
`servicio_audio_eq_reapply_test.dart` = 5. Total 21, 0 failures.

Final (Phase 5.4, re-run after ALL code changes, same command, same order):
8 / 5 / 3 / 5 = 21, 0 failures. **EXACT MATCH — same test names, same
order, same counts, byte-identical.** No regression in any of the 4
protected suites. Verified twice independently (once right after the
`servicio_audio.dart` wiring, once as the final Phase 5.4 gate) with
identical results both times.

One deliberate, disclosed exception to "nothing about the 4 protected files
changes": Phase 5.2 required a "5 failures → agotado, no 6th retry, no
hang/crash" test using the DEFAULT `maxReintentos: 5` (the existing test at
`servicio_audio_reconnect_test.dart:115-137` uses an abbreviated
`maxReintentos: 2`). Rather than add a 9th test into the protected file
(which would have changed its pass count from 8 to 9 and technically
violated the "exact pass count" gate), this was added to a NEW,
purpose-built file (`controlador_reconexion_local_test.dart`) instead,
testing the same `ControladorReconexion` class (already fully
unit-testable, source-agnostic by construction). This satisfies task 5.2's
substance without touching the protected file's contents or count at all.

## Diff size

Estimated: prod ~470 lines (`cola_local.dart` ~100 new,
`navegacion_auto.dart` ~180 added, `servicio_audio.dart` ~190 added/changed
net of the split), tests ~950 lines across 3 new/modified test files. Total
~1400+ lines — over the original ~850-950 estimate in tasks.md's Review
Workload Forecast, primarily because of the number of existing
`navegacion_auto_test.dart` assertions that needed explicit updates once
the page-0 prepend behavior changed, plus the dedicated open-question
regression file. Delivered as a single PR with `size:exception` per the
user's explicit, informed choice this session (told this was the
highest-risk change of the day, chose to proceed as one PR anyway).

## Deviations from design (disclosed)

1. **Mid-await race guard placement**: design's ADR-3 pseudocode describes
   the `avanceEsValido` guard as gating whether `_reproducirEntradaCola`
   gets called at all (guard, THEN call). Implemented instead as an
   optional `colaEsperada` parameter checked INSIDE
   `_reproducirEntradaCola`, immediately after its own URI resolve and
   before calling `_encolarCambioFuente`. This is functionally identical
   (same causal order: capture → await → guard → play) and avoids a
   redundant second `uriContenidoDePista` channel call, while preserving
   task 3.2's stricter acceptance criterion ("`_reproducirEntradaCola` is
   the ONLY other caller of `_encolarCambioFuente`").
2. **Resolve-failure handling not explicit in design's happy-path
   pseudocode**: when an auto-advance's `construirMediaItemColaLocal`
   resolves to `null` (dead/moved/permission-revoked local file, distinct
   from a `PlayerException` during actual playback), the queue is
   deactivated and stopped rather than left with a stuck `_avanzandoCola`
   latch. This is a defensive addition consistent with ADR-4's "no
   inconsistent state" principle, not explicitly scripted in the design's
   pseudocode.
3. **`androidCompactActionIndices` dynamic index**: not explicitly called
   out in tasks.md's acceptance criteria for 3.7, but necessary for
   correctness — when `_colaLocal != null`, `skipToPrevious` is prepended
   at index 0, so the compact-view highlighted action (play/pause) index
   shifts to `1` (`colaActiva ? 1 : 0`) to keep pointing at play/pause
   instead of skip-previous. The `_colaLocal == null` branch remains `[0]`,
   unchanged.
4. **Phase 5.2 test placement** — see "Regression discipline" above: added
   to a new file, not the protected `servicio_audio_reconnect_test.dart`,
   to preserve that suite's exact pass count.

## Risks / follow-ups for verify phase

- Phase 3's handler wiring (the highest-risk part of this change) is
  static-review-only by design — `PluriWaveAudioHandler` cannot be
  instantiated in unit tests. Correctness there rests on (a) the pure
  `cola_local.dart` functions being fully unit-tested and (b) careful
  manual diff review of the wiring, both completed in this pass, but a
  human/verify-phase re-read of `servicio_audio.dart`'s diff is still
  warranted given the stakes.
- Phase 6.1 (`flutter analyze`, `flutter test --coverage`, `flutter
  gen-l10n`) was explicitly out of scope for this apply pass (strict-TDD
  mode: only target test files were run) and remains a manual follow-up
  before merge.
- On-device / DHU manual QA for real car transport buttons and a genuine
  `ProcessingState.completed` emission is out of scope here (session
  precedent, per design's Testing Strategy table) and should be scheduled
  separately.

## Skill compliance

- `literal-encoding`: scan run over all touched/new `.dart` files
  (`cola_local.dart`, `navegacion_auto.dart`, `servicio_audio.dart`,
  `cola_local_test.dart`, `navegacion_auto_test.dart`,
  `controlador_reconexion_local_test.dart`) for `Ã.|â€|�` — 0 matches,
  passed.
- `work-unit-commits`: working tree left UNSTAGED per instruction — the
  orchestrator handles commit/push with a `[size:exception]` tag. No
  `git commit` was run by this agent.