pluriwave/openspec/changes/archive/2026-07-11-bt-device-identity/archive-report.md

Archive Report: Canonical Bluetooth Device Identity

Change: bt-device-identity
Archived: 2026-07-11
Status: ARCHIVED AND CLOSED
Archive Path: openspec/changes/archive/2026-07-11-bt-device-identity/
Spec Merged To: openspec/specs/bt-device-identity/spec.md (new capability domain)

---

Executive Summary

The bt-device-identity change is now archived with a PASS WITH WARNINGS verification verdict. All code-gated implementation work is complete across Phases 1–5 (41 of 57 tasks done, 6 N/A by design). Phase 7 (manual/on-device QA, 10 tasks, human sign-off gate) remains pending as the mandatory pre-shipping gate. The change restores stable Bluetooth device identity by acquiring BLUETOOTH_CONNECT at point-of-intent, guarding against the OS placeholder MAC, caching per-device names, and migrating corrupted placeholder-keyed entries. All test suites pass (102/102 tests), flutter analyze reports 0 issues, and the re-verify phase closed the single CRITICAL finding (CRITICAL-1: untested "rename survives re-pair" scenario — now covered by new task 3.10 composed regression test that passes against existing code).

---

Artifact Traceability

Artifact	Engram Observation ID	Location	Notes
Proposal	#2299	sdd/bt-device-identity/proposal	Root cause analysis, scope, approach, risks
Spec	#2304	sdd/bt-device-identity/spec; merged to openspec/specs/bt-device-identity/spec.md	7 requirement groups, 21 scenarios; on-disk version (openspec/changes/bt-device-identity/spec.md) reconciled and merged to new domain
Design	#2305	sdd/bt-device-identity/design	6 ADRs, technical approach, file changes, testing strategy
Explore	(embedded)	sdd/bt-device-identity/proposal (no separate observe)	Root cause evidence, bug analysis
Tasks	#2314	sdd/bt-device-identity/tasks	57 checkboxes: 41 complete (Phase 1–5), 6 N/A (Phase 6), 10 pending (Phase 7 human QA)
Apply-Progress	#2328	sdd/bt-device-identity/apply-progress	Batches 1/2/2b complete (Phases 1–5); Batch 3 (Phase 7) pending; full merged evidence of all 41 tasks
Verify-Report	#2329	sdd/bt-device-identity/verify-report	Initial FAIL (CRITICAL-1 untested scenario); re-verify PASS WITH WARNINGS (CRITICAL-1 closed via task 3.10); 15/21 scenarios COMPLIANT, 4/21 DEFERRED (manual QA), 2/21 N/A (l10n justified), 0/21 still UNTESTED

---

Implementation Completion

Phases 1–5: Code-Gated Work — COMPLETE

Phase	Description	Tasks	Status	Evidence
1	Kotlin permission plumbing (manifest, placeholder guard, composite fallback, permission request, re-emit)	1.1–1.8 (8)	8/8 [x]	Code-inspection verified; flutter analyze 0 issues
2	Dart permission contract (abstract method, fakes, interface tests)	2.1–2.5 (5)	5/5 [x]	All 3 fake implementers updated; contract tests pass
3	Dart platform-name cache + duplicate-entry guard (in-memory map, composites don't auto-create, regression tests)	3.1–3.10 (10)	10/10 [x]	49/49 estado_ecualizador_test.dart pass (incl. post-verify task 3.10)
4	Dart display fix + permission trigger (call sites updated, permission fires on toggle-ON)	4.1–4.8 (8)	8/8 [x]	11/11 pantalla_ajustes_test.dart pass; provider wiring resolved via passthrough
5	Dart one-time migration purge (guarded flag, exact-literal placeholder removal, idempotent)	5.1–5.10 (10)	10/10 [x]	20/20 servicio_ecualizador_test.dart pass; migration isolation verified

Phase 6: Localization — N/A (By Design)

Phase	Description	Tasks	Status	Rationale
6	Localization (l10n keys for all 13 locales IF UI copy is shown)	6.1–6.6 (6)	N/A	No in-app rationale sheet or migration-notice UI exists; OS BLUETOOTH_CONNECT dialog only; migration purge entirely silent; Phase 6 condition ("IF UI copy is shown") not met

Phase 7: Manual/On-Device QA — PENDING (Human Gate)

Phase	Description	Tasks	Status	Notes
7	Manual/on-device QA (permission dialog flow, real MAC after grant, rename survives re-pair, no duplicates, migration idempotency, locale rendering if Phase 6 ships)	7.1–7.10 (10)	0/10 [ ]	Mandatory human sign-off gate; requires real/emulated Android 12+ device; Kotlin permission path not unit-testable (code-inspected only); these 10 items are the ONLY remaining work for this change

Task Summary:

• 41 tasks complete ([x]) across Phases 1–5
• 6 tasks N/A ([ ] with justification) in Phase 6
• 10 tasks pending ([ ]) in Phase 7
• Total: 57 checkboxes, 0 unaccounted

---

Test Results

Unit/Widget Tests

Suite	Tests	Result	Notes
estado_ecualizador_test.dart	49/49	PASS	+1 from task 3.10 (was 48/48); Phase D regression group (D.1-D.5) confirmed green
pantalla_ajustes_test.dart	11/11	PASS	Display fix + permission trigger scenarios
servicio_ecualizador_test.dart	20/20	PASS	Migration tests including matrix-key and near-miss scenarios
servicio_dispositivo_audio_real_test.dart	10/10	PASS	Permission contract (MethodChannel invokeMethod)
servicio_dispositivo_audio_test.dart	7/7	PASS	Abstract contract tests
servicio_dispositivo_audio_toggle_test.dart	5/5	PASS	Ripple-fix (NullServicioDispositivoAudio) included
Total	102/102	PASS	—

Static Analysis

Tool	Result	Coverage
flutter analyze	0 issues	Whole project
rg (placeholder string checks)	No dead code (00:00:00:00:00:00 removed completely)	Kotlin, Dart

Code Coverage

• Exact-line coverage metrics not collected (per verification scope).
• Scenario-level mapping: 15/21 spec scenarios COMPLIANT (Dart-testable, all pass); 4/21 DEFERRED (manual QA); 2/21 N/A (l10n justified).
• CRITICAL-1 closed by new task 3.10 composed test (spec.md L95-100, rename survives re-pair).

---

Verification Summary

Verdict Evolution

Pass	Result	Finding
Initial (2026-07-11 00:44)	FAIL	CRITICAL-1: Untested Dart-testable scenario "rename persists after re-pair" (spec.md L95-100) — constituent behaviors tested individually (reconnect-dedup D.4, rename-priority 4.4), composition untested
Re-verify (2026-07-11 post-verify)	PASS WITH WARNINGS	CRITICAL-1 CLOSED: task 3.10 adds composed regression test; passes against existing code (coverage gap confirmed, not functional bug). WARNING-1 spec wording reconciled (composite shape documented as bt_a2dp:name:<name> per ADR-3). WARNING-2 cosmetic (arithmetic drift in apply-progress narrative, no code impact) accepted as-is.

Finding Breakdown

Severity	Count	Status
CRITICAL	1	CLOSED (task 3.10 composed regression test)
WARNING	2	CLOSED (WARNING-1, re-verify wording fix); OPEN/ACCEPTED (WARNING-2, cosmetic)
SUGGESTION	3	OPEN (non-blocking: wording nuance SUGGESTION-1, mock call-count pattern SUGGESTION-2, Engram housekeeping SUGGESTION-3)

Compliance Matrix Snapshot

Req.	Scenarios	Compliant	Deferred	N/A	Untested
BLUETOOTH_CONNECT at point-of-intent	2	0	2	0	0
Placeholder MAC guarded	5	4	1	0	0
Platform-name cache feeds display	3	3	0	0	0
Rename survives re-pair	2	1 (via 3.10)	1	0	0
No duplicate entries on transient	2	2	0	0	0
One-time guarded migration	6	6	0	0	0
Localization (conditional on UI copy)	2	0	0	2	0
Total	21	15	4	2	0

---

File Changes Summary

Estimated Changed Lines: ~450 (Kotlin ~90, Dart prod ~140, Dart tests ~58 post-verify, manifest ~1)
400-Line Budget Risk: High (mitigated by chained PR strategy; PR 1: Kotlin, PR 2: Dart, PR 3: l10n + manual QA)
Build Execution: Not run (per verification scope — flutter build explicitly excluded)

Kotlin (Code-Inspection Verified)

• android/app/src/main/AndroidManifest.xml: +1 permission declaration
• android/app/.../MainActivity.kt: ~90 lines (permission request code, placeholder guard, composite fallback, re-emit logic, doc comment updates)

Dart Production

• lib/servicios/servicio_dispositivo_audio.dart: Abstract + real impl of solicitarPermisoBluetooth()
• lib/estado/estado_ecualizador.dart: In-memory _nombresPlataforma cache, nombrePlataforma() getter, duplicate-entry guard update
• lib/pantallas/pantalla_ajustes.dart: Two nombreVisible() call sites updated, permission trigger added
• lib/servicios/servicio_ecualizador.dart: Migration constants and migrarClavesPlaceholder() function

Dart Tests

• test/estado/estado_ecualizador_test.dart: +58 lines (task 3.10 post-verify regression test)
• test/pantallas/pantalla_ajustes_test.dart: Display fix + permission trigger tests
• test/servicios/servicio_ecualizador_test.dart: Migration test suite (exact placeholder, matrix suffix, near-miss, idempotency)
• test/servicios/servicio_dispositivo_audio_real_test.dart: Permission contract tests
• test/helpers/fakes.dart: Fake implementers updated (ripple-fix: NullServicioDispositivoAudio also patched)

Localization

• lib/l10n/*.arb (13 files): 0 changes (Phase 6 N/A — no in-app copy shipped)

---

Deviations from Design

Documented and Signed Off:

1. Trigger-Point Deviation (Phase 4, Task 4.7): Design specified "on opening device-management UI" (StatefulWidget on-build hook). Actual: permission fires on toggle-turn-ON tap in _SeccionEcualizadorAvanzado (StatelessWidget). Rationale: avoids unnecessary StatelessWidget → StatefulWidget conversion; toggle-turn-ON satisfies both spec scenarios. Signed off by orchestrator.

2. Provider Wiring Resolution (Phase 4, Task 4.8): Design assumed ServicioDispositivoAudio would be a top-level Provider. Actual: not registered in app.dart. Solution: added solicitarPermisoBluetooth() passthrough on EstadoEcualizador (delegates to private field). Maintains test isolation, avoids ProviderNotFoundException.

No design deviations were introduced in Batch 2b (task 3.10 is test-only, zero production-code changes).

---

Risks and Mitigations

Risk	Likelihood	Status
Migration deletes legitimate data	Low	Exact-literal bt_a2dp:02:00:00:00:00:00 match only; all other keys preserved; Task 5.3 near-miss test confirms 02:00:00:00:00:01 is NOT purged
BT permission denied → unstable ids	Med	Composite bt_a2dp:name:<productName> fallback keeps app functional; re-prompt on next settings open; no crash path
Colon-delimiter key safety broken	Low	Single leading bt_a2dp: segment preserved; productName colons sanitized to -; eq_presets_matriz_v1 split-on-first-: remains valid (ADR-3, multi-device-eq ADR-3 RFC4122 rationale)
Kotlin permission flow has no precedent	Med	Copied verbatim from existing requestPostNotificationsPermission pattern (L306-318 struct); request codes distinct (4821/4822/4823); human verification in Phase 7
No Kotlin test harness	Med	Code-inspection verified against proven pattern; Phase 7 manual QA is the runtime gate

---

Next Steps

Mandatory Before Shipping

1. Phase 7 Manual/On-Device QA (pending, 10 tasks): Requires real or emulated Android 12+ device.

   • Permission dialog flow (grant/deny, no dialog at launch)
   • Real MAC after grant (7.3)
   • Rename survives re-pair without duplicates (7.5, the original bug report symptom)
   • Migration purge on affected install + idempotency (7.7–7.8)
   • Locale rendering if Phase 6 ships (7.9; N/A this change)
   • Sign-off (7.10) before merge

2. Chain Strategy (pending, from tasks.md): Orchestrator should confirm/name the chain strategy if chained PRs are used:

   • stacked-to-main: Each PR merges to main in order (fast, fix on the go)
   • feature-branch-chain: Tracker branch accumulates; PR #1→PR 2→PR 3 (rollback control)

Follow-Up Opportunities (Out of Scope)

• WARNING-1 (now closed): Spec wording reconciled during re-verify. Composite shape (bt_a2dp:name:<name>) is now documented in both spec and design.
• WARNING-2 (cosmetic, accepted): Arithmetic drift in apply-progress narrative (pre-existing test counts off by 3/2 respectively) — no functional impact. Accepted as-is per task brief.
• SUGGESTION-1/2/3 (non-blocking): Wording nuance (composite not single-entry), mock-call-count pattern, Engram conflict housekeeping — all flagged for future review.
• Broader transient-churn dedup (design Open Question): Deferred; acceptable now that MAC is canonical. Revisit if duplicates persist post-fix.

---

Archive Integrity

Moved From: openspec/changes/bt-device-identity/ → openspec/changes/archive/2026-07-11-bt-device-identity/
Verified Empty: Source folder no longer exists under changes/ (not a residual copy, true move)
Spec Merged: openspec/specs/bt-device-identity/spec.md created as new domain (not merged into multi-device-eq, which focuses on EQ preset resolution; bt-device-identity is about device identity + persistence)
Artifacts Preserved: All 6 openspec files (design, explore, proposal, spec, tasks, verify-report) + new state.yaml and this archive-report

---

Sign-Off

Archive Ready For: Production shipping (pending Phase 7 human QA sign-off)
Blocking Issues: None; Phase 7 is a known human gate, not a blocker
Recommendation: Proceed to Phase 7 manual QA; no code changes expected; expect 10 pass/fail items to be recorded against real device access

---

Appendix: Observation IDs for Traceability

• #2299: sdd/bt-device-identity/proposal (root cause, scope, approach)
• #2304: sdd/bt-device-identity/spec (21 scenarios, 7 requirement groups)
• #2305: sdd/bt-device-identity/design (6 ADRs, technical approach, testing strategy)
• #2314: sdd/bt-device-identity/tasks (57 checkboxes, 3 batches, phase status)
• #2328: sdd/bt-device-identity/apply-progress (Batches 1/2/2b merged evidence, 41 tasks complete)
• #2329: sdd/bt-device-identity/verify-report (PASS WITH WARNINGS, re-verify, CRITICAL-1 closed)

All artifacts archived and accessible at openspec/changes/archive/2026-07-11-bt-device-identity/ with full change history preserved for audit trail.