pluriwave/openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/archive-report.md

# Archive Report: android-auto-local-music-phase2

**Date**: 2026-07-19  
**Change**: android-auto-local-music-phase2  
**Artifact Store Mode**: Hybrid (OpenSpec files + Engram persistence)  
**Status**: Complete — Change archived and closed

## Executive Summary

The android-auto-local-music-phase2 change is fully implemented, verified with 0 CRITICAL and 2 WARNINGs (documentation-accuracy only, already corrected), and has been archived. Phase 2 of the local-music feature is now complete, delivering real embedded metadata resolution, quality-based sort navigation, and alphabetical name buckets for browsable audio files in Android Auto. Only Phase 3 (subfolder scoping refinements, shuffle) remains as planned future work. Outstanding pre-release gate: native metadata-extraction path (MediaMetadataRetriever, FileProvider art cache/LRU) requires on-device/DHU validation across all local-music phases before production release.

## Change Artifacts

### Specification Artifacts

**Base Spec**: `openspec/specs/android-auto-media/spec.md`
- **Status**: MERGED with delta requirements
- **Changes**:
  - MODIFIED: "Local Music Browsable Tree" requirement expanded to include metadata resolution scenarios (title/art reflection, embedded-metadata fallback)
  - ADDED: "Local Music Sort Mode Navigation" requirement (name sort, quality sort by bitrate)
  - ADDED: "Local Music Alphabetical Name Buckets" requirement (A-F/G-M/N-S/T-Z letter ranges)
  - ADDED: "Local Track Embedded Album Art Display" requirement (static URI resolution, fallback handling)

**Delta Spec**: `openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/specs/android-auto-media/spec.md`
- Archived for traceability

### Change Folder Artifacts

**Archived Location**: `openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/`

**Contents**:
- `proposal.md` — Phase 2 scope, intent, capabilities, and ADRs (metadata extraction via `MediaMetadataRetriever`, on-demand parsing, LRU cache)
- `design.md` — Technical architecture (5 ADRs, data flow, file changes, testing strategy, open questions on 150-track cap and 256-file/32MB art budget)
- `tasks.md` — 37 implementation tasks across 4 phases (model/native/cache/sort/buckets/regression)
- `apply-progress.md` — All 37/37 tasks completed, 137/137 tests passing, single PR with `size:exception`, corrected test counts (18 vs 19 claimed)
- `verify-report.md` — PASS WITH WARNINGS; 0 CRITICAL, 2 WARNINGs (test-count inaccuracy corrected before archive), implementation verified sound
- `specs/android-auto-media/spec.md` — Delta spec for archive trail

## Merged Specification Requirements

### Modified Requirement: Local Music Browsable Tree
Expanded to include:
- Track title resolution: shows embedded metadata when available, falls back to filename
- Track art resolution: shows embedded album art when available, falls back to generic placeholder
- Graceful degradation: no exceptions on metadata unavailability, continues browsing

### New Requirement: Local Music Sort Mode Navigation
- Browsable, non-playable sort-mode entries on page 0
- "By name" (filename order) always available
- "By audio quality" (bitrate descending) available when folder <= 150 tracks
- Mirrors `ordenarEmisoras(..., calidad)` comparator pattern

### New Requirement: Local Music Alphabetical Name Buckets
- Browsable, non-playable letter-range folders (A-F, G-M, N-S, T-Z)
- Metadata-free partitioning (uses only filename)
- Available when folder > 50 tracks
- Enables name-based filtering on legacy `MediaBrowserService` surface

### New Requirement: Local Track Embedded Album Art Display
- Static URI resolution via FileProvider cache (`content://...fileprovider...`)
- Art cache with LRU eviction (256 files / 32 MB budget)
- Graceful fallback to generic rotating placeholder art

## Implementation Summary

### Delivery Strategy
- Mode: Single PR with `size:exception` (user's established preference for high-risk changes this session)
- Test Mode: Strict TDD (all Dart behavior-changing code), Static-review-only (native Kotlin per project precedent)
- Result: 1979 changed lines, all 137/137 tests passing

### Test Coverage
- 114 tests in `navegacion_auto_test.dart` (encode/decode, buckets, quality sort, page-0 wiring, fallbacks, collision guards)
- 18 tests in `musica_local_auto_test.dart` (LRU cache, metadata channel call, null tolerance)
- 5 tests in `pista_local_test.dart` (DTO construction)
- **Total verified**: 137/137 pass, 0 failures

### Verification Status
- **Verdict**: PASS WITH WARNINGS
- **CRITICAL Issues**: None
- **WARNINGs** (both documentation-accuracy, corrected):
  - Apply-progress claimed 138/138 tests (19 in musica_local_auto_test.dart); actual 137/137 (18 tests). Corrected in apply-progress before archive.
  - Apply-progress claimed 9 fixture corrections; actual 8. Corrected in apply-progress before archive.
- **SUGGESTIONs** (non-blocking):
  - Native Kotlin code (readAudioMetadataBatch, art cache, LRU trim) remains static-review-only per established project precedent (no build/DHU environment)
  - On-device validation of 150-track cap and 256-file/32MB art budget deferred to pre-release gate (design "Open Questions")
  - Cosmetic CRLF line-ending warnings (not defects)

### Key Design Decisions Verified

1. **Embedded-art delivery**: FileProvider cache (content:// URI) — reuses existing authority, zero new manifest surface
2. **Metadata cache**: Flat 256-entry LRU-by-access in `navegacion_auto.dart` — ensures paging doesn't evict earlier pages
3. **Quality-sort threshold**: Offered when folder <= 150 tracks; above that, name + buckets only (head-unit latency guard)
4. **Media-ID collision safety**: `carpeta_local_ord:` and `carpeta_local_bucket:` prefixes proven non-colliding against all 6 pre-existing prefixes
5. **Page-scoping invariant**: Metadata resolved only for the requested page's 50 items, never the whole folder (except quality-sort, which is opt-in)

## Rollback Profile

Phase 2 is fully additive over Phase 1. If needed:
- Remove `readAudioMetadataBatch` native call
- Drop `_ord` and `_bucket` media-id prefixes
- Restore filename titles + placeholder art
- Phase 1 browse/play/paging remains fully functional

## Outstanding Pre-Release Gates

**Native code validation** (applies to Phases 1, paging, and 2):
- `MediaMetadataRetriever` bitrate/sample-rate/embedded-picture extraction with real SAF URIs (on-device/DHU)
- FileProvider art cache write/read on actual Android file system
- 150-track quality-sort wall-clock latency (design "Open Questions")
- 256-file / 32 MB art cache eviction under realistic browsing patterns

No code changes required — these are validation gates for go-live, not SDD cycle blockers.

## Archive Checklist

- [x] Delta spec merged into main spec (`openspec/specs/android-auto-media/spec.md`)
- [x] All 4 new/modified requirements integrated into spec source of truth
- [x] Change folder moved to archive with ISO date prefix: `openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/`
- [x] All artifacts (proposal, design, tasks, apply-progress, verify-report, delta spec) copied to archive
- [x] Archive report written to both filesystem and engram
- [x] Verification passed (PASS WITH WARNINGS, 0 CRITICAL)

## SDD Cycle Completion

- **Proposed**: android-auto-local-music-phase2
- **Specified**: 1 modified + 3 added requirements
- **Designed**: 5 ADRs, page-scoping invariant, media-ID codec, LRU cache
- **Tasked**: 37 implementation tasks (4 phases, model/native/cache/sort/buckets)
- **Applied**: All 37 tasks completed, single PR, 1979 changed lines, 137/137 tests green
- **Verified**: PASS WITH WARNINGS (0 CRITICAL, 2 WARNINGs corrected)
- **Archived**: Change folder and all artifacts persisted

**Next**: Phase 3 (subfolder scoping, shuffle) when scheduled. Entire local-music feature remains gated on pre-release native validation.