pluriwave/openspec/changes/alarm-volume-ramp-restore/tasks.md

Tasks: Alarm Volume Ramp & Device-Volume Immunity

Review Workload Forecast

Field	Value
Estimated changed lines	260-360 (7 files: manifest, 2 Kotlin, 3 Dart, 1 new Dart interface method pair + 3 test files)
400-line budget risk	Medium
Chained PRs recommended	Yes
Suggested split	PR 1 (Slice 1 manifest+FGS) -> PR 2 (Slice 2 volume override/restore) -> PR 3 (Slice 3 fade-in dedup)
Delivery strategy	ask-on-risk
Chain strategy	pending

Decision needed before apply: Yes Chained PRs recommended: Yes Chain strategy: pending 400-line budget risk: Medium

Suggested Work Units

Unit	Goal	Likely PR	Notes
1	Fix FGS manifest+runtime type mismatch (Slice 1)	PR 1	Independent, near-zero risk, own rollback; mandatory Android 14+ device gate
2	Ring-scoped STREAM_MUSIC override + idempotent restore (Slice 2)	PR 2	Depends on PR 1 landing (FGS must start before override matters); own rollback via guard-disable
3	Dedup fade-in driver at handoff (Slice 3)	PR 3	Independent of PR 2; can reorder before PR 2 if preferred; own rollback (revert gate)

---

Phase 1: FGS Manifest + Runtime Type Fix (Slice 1 — code-inspection + manual QA)

PHASE CANCELLED (orchestrator, 2026-07-11) — resolution of the BLOCKED note below: the target constants are fictional (verified against the local SDK), the existing mediaPlayback|systemExempted declaration is confirmed correct, and Root Cause B is withdrawn. Tasks 1.1-1.7 ship no code. See the correction banner in design.md and the amended Requirement in specs/native-alarms/spec.md. Slices 2 and 3 proceed unaffected.

• 1.1 Edit android/app/src/main/AndroidManifest.xml:57 — change PluriWaveAlarmService android:foregroundServiceType from "mediaPlayback|systemExempted" to "mediaPlayback|alarm".
• 1.2 Edit android/app/src/main/AndroidManifest.xml:6 — replace <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SYSTEM_EXEMPTED"/> with <uses-permission android:name="android.permission.FOREGROUND_SERVICE_ALARM"/>.
• 1.3 Edit PluriWaveAlarmService.kt:118-119 — change startForeground type constants from FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK or FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED to FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK or FOREGROUND_SERVICE_TYPE_ALARM. 1.1-1.3 are ONE atomic unit — a manifest-only or runtime-only edit leaves the API 34+ exception alive; do not split across commits.

BLOCKED (sdd-apply, 2026-07-11): FOREGROUND_SERVICE_TYPE_ALARM / android.permission.FOREGROUND_SERVICE_ALARM do NOT exist in the Android SDK. Verified via javap -constants against android.content.pm.ServiceInfo and android.Manifest$permission in the local android-34/android-35/android-36 platform android.jars, plus a full FOREGROUND_SERVICE_TYPE_* field sweep of api-versions.xml. The only FGS types that exist through API 36 are: camera, connectedDevice, dataSync, health, location, manifest, mediaPlayback, mediaProcessing, mediaProjection, microphone, phoneCall, remoteMessaging, shortService, specialUse, systemExempted — no alarm variant. Edits 1.1-1.3 were applied then reverted (git checkout --) to avoid landing an unresolved-Kotlin-reference / invalid-manifest-enum compile break that flutter analyze cannot catch (Dart-only) and that this task explicitly forbids validating via flutter build/gradle. This reconfirms the identical finding already recorded in app-quality-and-native-alarms (T-S1-03/T-S1-04), which used systemExempted/FOREGROUND_SERVICE_SYSTEM_EXEMPTED for the same reason — see design #2310's own "Open Questions" section, which flagged but did not resolve this before approval. Design #2310 / tasks #2316 need correction before Slice 1 can proceed: either identify a real SDK-backed fix for the API 34+ ForegroundServiceTypeException, or confirm systemExempted was already correct and the actual Slice 1 defect (if any) lies elsewhere. Working tree is clean — no diff left on either file.

• 1.4 Static check: rg 'foregroundServiceType' android/app/src/main/AndroidManifest.xml shows alarm, not systemExempted, on the PluriWaveAlarmService line.
• 1.5 Static check: rg 'FOREGROUND_SERVICE_ALARM|FOREGROUND_SERVICE_SYSTEM_EXEMPTED' android/app/src/main/AndroidManifest.xml shows FOREGROUND_SERVICE_ALARM present and FOREGROUND_SERVICE_SYSTEM_EXEMPTED absent.
• 1.6 Static check: rg 'FOREGROUND_SERVICE_TYPE_ALARM|FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED' android/.../PluriWaveAlarmService.kt shows TYPE_ALARM present and TYPE_SYSTEM_EXEMPTED absent — confirms manifest/runtime match (Requirement: Manifest declares alarm-eligible FGS, Scenario "Manifest declares required FGS type and permission").
• 1.7 flutter analyze (no flutter build) — confirm no lint regressions from these edits (none expected; XML/Kotlin only).

Phase 2: Ring-Scoped Volume Override — Kotlin Channel Methods (Slice 2, code-inspection only)

• 2.1 In MainActivity.kt, add @Volatile companion-scoped state: mediaVolumeOverridden: Boolean and capturedMediaVolume: Int? to track ring-scoped override without surviving process death (documented residual gap).
• 2.2 In MainActivity.kt's alarm_scheduler when (call.method) block (near L79-218), add "overrideMediaVolumeForRing" case: capture current AudioManager.STREAM_MUSIC volume into capturedMediaVolume (only if not already overridden — idempotent guard), then setStreamVolume(STREAM_MUSIC, getStreamMaxVolume(STREAM_MUSIC), 0) (flag 0 = no FLAG_SHOW_UI, no slider flash). Set mediaVolumeOverridden = true. fraction arg accepted but unused (reserved, default 1.0 = max reference level, per design).
• 2.3 In the same when block, add "restoreMediaVolume" case: no-op if mediaVolumeOverridden == false (idempotent guard); otherwise setStreamVolume(STREAM_MUSIC, capturedMediaVolume, 0), then clear mediaVolumeOverridden = false and capturedMediaVolume = null.
• 2.4 Add a public restoreMediaVolumeBestEffort() method on MainActivity (or companion) that PluriWaveAlarmService can call as a backstop when the engine is alive.
• 2.5 In PluriWaveAlarmService.kt's stopAlarm() (L356-381) and onDestroy() (L501-504), call the best-effort restore before/alongside existing teardown, guarded so it never throws if the engine/activity is unavailable.
• 2.6 Static check: rg 'overrideMediaVolumeForRing|restoreMediaVolume' android/.../MainActivity.kt shows both channel cases present.
• 2.7 Static check: rg 'mediaVolumeOverridden' android/.../MainActivity.kt shows the guard read in BOTH the override and restore branches (idempotence, Requirement: Ring-scoped device-volume override, Scenario "Restore is idempotent across double-exit paths").
• 2.8 Static check: rg 'restoreMediaVolumeBestEffort' android/.../PluriWaveAlarmService.kt shows it called from both stopAlarm and onDestroy.
• 2.9 flutter analyze — confirm no Kotlin/lint regressions.

Phase 3: Ring-Scoped Volume Override — Dart Port + Wiring (Slice 2, strict TDD)

• 3.1 (RED) In test/servicios/servicio_alarmas_android_test.dart, add a test asserting ServicioAlarmasAndroid.forzarVolumenMediaParaAlarma(1.0) invokes channel method overrideMediaVolumeForRing with {'fraction': 1.0}, using the existing mock-channel pattern (MethodChannel('pluriwave/alarm_scheduler') + llamadas list). Run flutter test — confirm it fails (method does not exist).
• 3.2 (RED) In the same file, add a test asserting ServicioAlarmasAndroid.restaurarVolumenMedia() invokes channel method restoreMediaVolume with no args. Run flutter test — confirm it fails.
• 3.3 (GREEN) Add Future<void> forzarVolumenMediaParaAlarma(double fraccion) and Future<void> restaurarVolumenMedia() to PuertoAlarmasAndroid (abstract, lib/servicios/servicio_alarmas_android.dart) and implement both on ServicioAlarmasAndroid using the existing _logAndInvokeVoid helper pattern. Run flutter test — confirm 3.1-3.2 pass.
• 3.4 (GREEN) Extend test/helpers/fakes_alarmas.dart's FakePuertoAlarmasAndroid: implement the two new abstract methods, recording calls into new lists volumenForzado: List<double> and volumenRestaurado: int (call count) so widget tests can assert invocation order/count.
• 3.5 (RED) In test/pantallas/pantalla_alarma_sonando_dismiss_guard_test.dart (or a new focused test file), add a widget test asserting _silenciarAudio -> restore is called exactly once on _detener() (dismiss) using env.android.volumenRestaurado. Run flutter test — confirm it fails.
• 3.6 (RED) Add the equivalent test for _posponer() (snooze) — restore called exactly once. Run flutter test — confirm it fails.
• 3.7 (RED) Add a test asserting restore is called at most once total even when both _silenciarAudio() (inside _detener) and dispose() run in sequence (idempotence at the Dart call-site level — the widget always calls restore in dispose() too, per design; assert the FAKE'S restore counter, not double-invocation of the real guard, since idempotence itself lives in Kotlin). Run flutter test — confirm it fails.
• 3.8 (GREEN) In lib/pantallas/pantalla_alarma_sonando.dart, call context.read<EstadoAlarmas>().android.restaurarVolumenMedia() inside _silenciarAudio() (L202-213, alongside _liberarAudioLocal()/radio.audio.pausar(), wrapped in its own try/catch so a failure never blocks dismiss/snooze) AND inside dispose() (L238-244). Run flutter test — confirm 3.5-3.7 pass.
• 3.9 (RED) In test/pantallas (widget test, or a lighter unit-style test on app.dart's ring-start seam if testable in isolation), add a test asserting forzarVolumenMediaParaAlarma is invoked when an alarm ring starts, at the TOP of _prearrancarAudioAlarma in lib/app.dart (BEFORE the if (emisora == null) return; early exit at L367) — the override must apply even when the alarm uses the fallback WAV path, not only the station path. Run flutter test — confirm it fails.
• 3.10 (GREEN) In lib/app.dart, call context.read<EstadoAlarmas>().android.forzarVolumenMediaParaAlarma(1.0) as the FIRST statement inside _prearrancarAudioAlarma (L365), before the emisora == null early return. Run flutter test — confirm 3.9 passes.
• 3.11 (RED) Add a test asserting the override/restore channel methods are NEVER invoked during normal radio playback with no alarm ringing (Requirement: Ring-scoped device-volume override, Scenario "Normal radio playback never triggers the override") — assert env.android.volumenForzado stays empty across a plain play/pause cycle on EstadoRadio outside any alarm flow. Run flutter test — confirm it fails or passes vacuously (should already pass since no other code path calls these methods yet — treat as a REGRESSION GUARD, not a RED/GREEN pair, if 3.3-3.10 are already in place).
• 3.12 (REFACTOR) Run flutter test for the full suite plus flutter analyze — confirm no regressions in existing alarm/radio tests.

Phase 4: Fade-In Dedup at Handoff (Slice 3, strict TDD)

• 4.1 (RED) In test/pantallas/pantalla_alarma_sonando_test.dart (or a new focused fade-in test file), add a widget test asserting the Dart fade-in ramp (observable via FakeServicioAudio/fallback player volume changes) does NOT start before confirmarAudioFlutter has been invoked on the android port (i.e., before _confirmarAudioFlutterListo() runs) — assert env.android.detenidas (which confirmarAudioFlutter appends to, per FakePuertoAlarmasAndroid.confirmarAudioFlutter) is non-empty before any volume-ramp step is observed. Run flutter test — confirm it fails (current code starts the ramp at L66 immediately after radio.reproducir, before confirmation).
• 4.2 (RED) Add a test asserting the fade-in DOES start once _confirmarAudioFlutterListo() has run (radio path via estadoStream emitting reproduciendo, or fallback path via _iniciarFallback) — the ramp must still function end-to-end after the gate. Run flutter test — confirm it fails or is trivially satisfied depending on 4.1's fixture; treat 4.1+4.2 as one RED pair validating gate correctness both ways.
• 4.3 (GREEN) In lib/pantallas/pantalla_alarma_sonando.dart, remove the _iniciarFadeIn() call at L66 (radio path, currently fires immediately after radio.reproducir(emisora)) and the one at L96 (fallback path, currently fires before _confirmarAudioFlutterListo() at L97); move the single _iniciarFadeIn() invocation INTO _confirmarAudioFlutterListo() (L133-139) so it fires exactly once, after the _audioFlutterConfirmado guard, for both the radio and fallback paths. Run flutter test — confirm 4.1-4.2 pass.
• 4.4 (REFACTOR) Re-run the full pantalla_alarma_sonando_test.dart and pantalla_alarma_sonando_dismiss_guard_test.dart suites — confirm no existing fade/dismiss/snooze assertions regressed from moving the ramp start point.
• 4.5 flutter analyze and dart format . — confirm clean formatting/lint state for all Slice 3 edits.

Phase 5: Manual/On-Device QA (mandatory human gate — Android 14+ physical or emulator device)

• 5.1 Set device media (STREAM_MUSIC) volume to 0. Trigger an alarm. Confirm the alarm rings audibly for its full duration, not just the pre-handoff native window (Scenario "Alarm is audible when device media volume is 0").
• 5.2 Confirm PluriWaveAlarmService starts without ForegroundServiceTypeException on an Android 14+ (API 34+) device when the alarm fires from a background/killed-app broadcast context (Scenario "Native service starts from broadcast context on Android 14+").
• 5.3 Note the original device media volume before triggering the alarm; dismiss the alarm; confirm media volume is restored to exactly the pre-alarm value (Scenario "Dismiss restores the original captured volume").
• 5.4 Repeat 5.3 for snooze instead of dismiss (Scenario "Snooze restores the original captured volume").
• 5.5 Listen across the native-to-Flutter handoff window; confirm there is no audible double-ramp/volume jump at the moment confirmarAudioFlutter fires (Scenario "No double-ramp interleaving at handoff").
• 5.6 With no alarm ringing, play/pause normal radio repeatedly and confirm device volume controls behave exactly as before this change (no override side effects) — Scenario "Normal radio playback never triggers the override".
• 5.7 Optional/best-effort: force-kill the app mid-ring and confirm the residual-volume-override gap is no worse than documented (Scenario "App killed mid-ring — best-effort restore only"; known accepted gap, not a blocking QA failure).
• 5.8 Record QA sign-off (device model, Android version, pass/fail per scenario) before sdd-verify/merge.

Phase 6: Final Static Sweep

• 6.1 Full-repo rg 'systemExempted|SYSTEM_EXEMPTED' across android/app/src/main — confirm zero remaining references (fully dropped, not kept alongside alarm).
• 6.2 flutter test (full suite) and flutter analyze — final clean run before requesting review.
• 6.3 dart format . — confirm no formatting diffs remain uncommitted.