pluriwave/openspec/specs/native-alarms/spec.md

Native Alarms Specification

Purpose

Native (Kotlin) foreground-service behavior for ringing alarms: reliable start from a broadcast context on Android 14+ via the correct foreground-service-type declaration, and sole native ring-audio ownership — PluriWaveAlarmService is the only audio source for the entire ring, on STREAM_ALARM via its own MediaPlayer, with an exponential dB fade-in ceiling, manually requested/abandoned transient audio focus, and a silent notification channel. System volumes are never written, so nothing ever needs restoring; the Flutter ringing screen is pure UI that only drives Stop/Snooze through EstadoAlarmas.

Requirements

Requirement: Manifest declares alarm-eligible foreground service

foregroundServiceType="mediaPlayback|systemExempted" on the PluriWaveAlarmService <service> element in AndroidManifest.xml is the correct, verified declaration for an alarm-clock app holding exact-alarm permissions that starts a foreground service from an AlarmManager broadcast on API 34+. FOREGROUND_SERVICE_TYPE_ALARM and android.permission.FOREGROUND_SERVICE_ALARM do NOT exist anywhere in the Android SDK (verified via javap -constants on android-34/35/36 platform jars and a full api-versions.xml sweep — 13 real FGS types, no alarm variant); do not attempt to introduce them.

Scenario: Manifest keeps the verified-correct FGS declaration

Testability: static/grep-verifiable

• GIVEN the built AndroidManifest.xml
• WHEN the PluriWaveAlarmService <service> element is inspected
• THEN android:foregroundServiceType MUST be mediaPlayback|systemExempted
• AND the runtime startForeground type constants in PluriWaveAlarmService.kt MUST match the manifest declaration

Scenario: Native service starts from broadcast context on Android 14+

Testability: manual on-device QA (Android 14+; agent cannot install/verify)

• GIVEN an alarm is scheduled and the app is not foregrounded
• WHEN PluriWaveAlarmReceiver.onReceive(ACTION_FIRE) starts PluriWaveAlarmService
• THEN it MUST start without ForegroundServiceTypeException
• AND the alarm MUST be audible via the native USAGE_ALARM player

Requirement: Sole native ring-audio ownership

PluriWaveAlarmService MUST be the only audio source for the whole ring, on STREAM_ALARM via its own MediaPlayer. No Dart player or second audible source MUST play.

Scenario: Media volume 0 does not silence the ring

Testability: on-device QA (audio routing) + flutter test with fakes

• GIVEN device STREAM_MUSIC volume is 0
• WHEN an alarm fires
• THEN it MUST be audible via the service's STREAM_ALARM player
• AND no Dart audio path (EstadoRadio) MUST run

Scenario: Fire notification posts with no sound

Testability: code-inspection + on-device QA

• GIVEN channel pluriwave_alarm_fire_v3
• WHEN the ringing notification posts
• THEN it MUST carry no sound; the player MUST be the only audible source

Scenario: Three-stage fallback preserved, single fade anchor

Testability: code-inspection + on-device QA

• GIVEN the primary station fails within its timeout
• WHEN the service advances station -> fallback station -> WAV
• THEN whichever stage starts MUST get the same fade curve, anchored at ring start

Requirement: Exponential dB fade-in ceiling

With fadeInSegundos > 0: gainDb = fraction*40-40, curve = 10^(gainDb/20) on a 50ms tick, setVolume(s * curve), s = per-alarm volumen as ceiling. With fadeInSegundos == 0: start directly at s.

Scenario: Fade rises exponentially to the ceiling

Testability: code-inspection (curve formula)

• GIVEN fadeInSegundos > 0, volumen = s
• WHEN the ring starts
• THEN volume at t=0 MUST equal s * 10^(-40/20) (~1% of s), rising every 50ms
• AND volume at t=fadeInSegundos MUST equal exactly s

Scenario: No-fade path starts pop-free

Testability: code-inspection + on-device QA

• GIVEN fadeInSegundos == 0
• WHEN the ring starts
• THEN setVolume(s) MUST be applied before start(), with no pop

Requirement: Manual transient focus; no system volume writes

The service MUST request AUDIOFOCUS_GAIN_TRANSIENT on STREAM_ALARM and abandon it at ring end. setStreamVolume MUST NOT be called on any stream, ever.

Scenario: Focus requested at start, abandoned at end

Testability: code-inspection + on-device QA (dumpsys audio)

• GIVEN the ring is about to start
• WHEN startAlarm runs
• THEN AUDIOFOCUS_GAIN_TRANSIENT MUST be requested on STREAM_ALARM
• AND WHEN the ring ends THEN focus MUST be abandoned

Scenario: Dismiss, snooze, and back tear down with nothing to restore

Testability: on-device QA + flutter test with fakes

• GIVEN an alarm is ringing
• WHEN the user dismisses, snoozes, or triggers back
• THEN the player MUST stop, focus MUST be abandoned, and foreground removed
• AND no setStreamVolume call MUST have occurred for this ring

Requirement: Notification channel migration v2 -> v3

The service MUST create pluriwave_alarm_fire_v3 (no sound) and delete pluriwave_alarm_fire_v2 exactly once, guarded by a migration flag (same pattern as v1->v2).

Scenario: v2 deleted exactly once on upgrade

Testability: code-inspection (migration guard) + on-device QA

• GIVEN a device with pluriwave_alarm_fire_v2 already created
• WHEN the service next ensures its channel
• THEN _v3 MUST be created and _v2 deleted; a re-run MUST be a no-op

Requirement: Ring screen is pure UI

PantallaAlarmaSonando MUST only call EstadoAlarmas.finalizarEjecucion/posponerAlarma from Stop/Snooze/back. It MUST NOT control any audio player or volume/handoff channel. PuertoAlarmasAndroid MUST NOT expose confirmarAudioFlutter, forzarVolumenMediaParaAlarma, or restaurarVolumenMedia.

Scenario: Buttons and back call only EstadoAlarmas

Testability: flutter test with fakes

• GIVEN the ringing screen is displayed
• WHEN Stop, a Snooze option, or back is triggered
• THEN only finalizarEjecucion/posponerAlarma MUST be called
• AND zero calls MUST reach EstadoRadio.audio or a removed channel method

Scenario: Reduced Android port surface

Testability: static/compile-verifiable (Dart analyzer) + flutter test

• GIVEN PuertoAlarmasAndroid and its implementations/fakes
• WHEN inspected after this change
• THEN confirmarAudioFlutter, forzarVolumenMediaParaAlarma, restaurarVolumenMedia MUST NOT exist

Non-Functional Notes

• No new user-visible strings; no l10n work required across the 13 supported locales.