docs(openspec): archive android-auto-local-music-phase2
Merges its delta requirements into the android-auto-media base spec. Completes Phase 2; only Phase 3 (subfolder scoping, shuffle) remains. On-device validation of the native metadata path is still an outstanding pre-release gate across all local-music phases shipped today.
This commit is contained in:
+1
-1
@@ -94,7 +94,7 @@ Tasks 1.4–1.8 (`readAudioMetadataBatch`, `extraerMetadatosPista`, `cachearArte
|
||||
flutter test test/servicios/navegacion_auto_test.dart test/servicios/musica_local_auto_test.dart test/modelos/pista_local_test.dart --concurrency=1 --timeout=60s
|
||||
→ 137/137 passed, 0 failed
|
||||
- navegacion_auto_test.dart: 114/114
|
||||
- musica_local_auto_test.dart: 19/19
|
||||
- musica_local_auto_test.dart: 18/18 (corrected from initially claimed 19)
|
||||
- pista_local_test.dart: 5/5
|
||||
```
|
||||
|
||||
+133
@@ -0,0 +1,133 @@
|
||||
# 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.
|
||||
+1
-1
@@ -60,7 +60,7 @@ None.
|
||||
|
||||
### WARNING
|
||||
1. Apply-progress test-count self-report inaccurate: claims 138/138 (114+19+5); actual is 137/137 (114+18+5). musica_local_auto_test.dart has 18 tests, not 19 (verified by both test-runner output and a static test( count). All 137 real tests pass - this is a reporting-accuracy issue, not a functional defect, but it is the third apply-progress numeric discrepancy flagged this session per the orchestrator own warning, and should be corrected before archive.
|
||||
2. Apply-progress "9 fixtures" claim off by one: git diff shows 8 pre-existing .single assertions converted to .singleWhere(pista-prefixed), not 9. The mechanism/rationale of the fix is verified genuine and non-weakening (narrows to the track item, does not drop any check), but the count itself is inaccurate.
|
||||
2. Apply-progress "9 fixtures" claim off by one: git diff shows 8 (not 9) pre-existing .single assertions converted to .singleWhere(pista-prefixed), not 9. The mechanism/rationale of the fix is verified genuine and non-weakening (narrows to the track item, does not drop any check), but the count itself is inaccurate.
|
||||
|
||||
### SUGGESTION
|
||||
- Native Kotlin (readAudioMetadataBatch/art cache/LRU trim) remains static-review-only per established project precedent - no build/DHU available in this environment. Design own "Open Questions" already flags the 150-track cap and 256-file/32MB art budget as needing on-device validation before this ships to real hardware; treat that as a pre-merge/pre-release gate, not a blocker for this SDD cycle.
|
||||
Reference in New Issue
Block a user