pluriwave/openspec/changes/archive/2026-07-12-native-alarm-ring/design.md

# Design: Native Alarm Ring

Reads: `proposal.md` (#2388), `explore.md` (#2387). This is the HOW at the architectural
level. Task breakdown lives in `tasks.md` (next phase).

## 1. Context and constraints

The ring failed 5 on-device iterations under a split-ownership design (Dart ramp → hand off to
native → override `STREAM_MUSIC` → restore). Root cause: two audio owners (Dart `just_audio`
on `STREAM_MUSIC` and the native `MediaPlayer` on `STREAM_ALARM`) fighting the alarm FGS.

The rebuild collapses ownership to ONE: `PluriWaveAlarmService` is the sole ring-audio owner
for the entire ring. Flutter becomes display-only. This is AOSP DeskClock's `AsyncRingtonePlayer`
shape. The current native service is ~80% there; the change mostly DELETES accidental complexity.

Hard constraints (from exploration, unchanged by this design):
- Scheduling stack, receiver `ACTION_FIRE` ordering, wake-lock/FGS-before-audio ordering,
  snooze truth-ownership (5 entry points), pre-notice + snooze-countdown chains, id-scoped stop.
- No system stream volume is ever written (`setStreamVolume` forbidden on every stream).
- Kotlin is not agent-compilable → on-device QA is the acceptance gate.

Verified facts (read in full this phase):
- Ring channel `pluriwave_alarm_fire_v2` is referenced ONLY by `PluriWaveAlarmService`
  (`buildNotification` L425, companion L554, `ensureChannel` L632). Pre-notice + snooze-countdown
  use a SEPARATE channel `pluriwave_alarm_pre_notice` (`PluriWaveAlarmReceiver.CHANNEL_ID`, built
  in `AlarmScheduler.ensurePreNoticeChannel`). The channel bump is fully scoped to the ring.
- `PluriWaveBootReceiver` only calls `reschedulePersistedAlarms()` — no FGS from boot (A15+ safe).
- The screen-exit stop path is intact: `finalizarEjecucion(id)` → `ocultarNotificacionAlarma(id)`
  → channel `dismissAlarmNotification` → `PluriWaveAlarmService.stop(ctx,id)` + `dismissFireNotification(id)`.
  In `stopAlarm`, `id == activeAlarmId` takes the FULL-teardown branch; a different id only cancels
  that id's notification. Id-scoped stop for the ACTIVE id is CONFIRMED working.
- `minSdk = flutter.minSdkVersion` → the pre-O audio-focus branch is potentially reachable; the
  focus API must be version-guarded.

## 2. Architecture approach

Single-owner native audio, thin Dart UI, no cross-boundary audio protocol.

```
ACTION_FIRE ─→ PluriWaveAlarmReceiver ─→ PluriWaveAlarmService.startAlarm
                                              │  wake lock → startForeground(silent v3) BEFORE audio
                                              │  request AUDIOFOCUS_GAIN_TRANSIENT (USAGE_ALARM)
                                              │  capture fade anchor (elapsedRealtime)
                                              ▼
                              startAudio ─→ 3-stage fallback (station → fallback station → WAV)
                                              │  each source: setVolume(computeFadeVolume(...)) BEFORE start
                                              │  ONE ring-anchored 50 ms fade Handler loop (dB curve)
                                              ▼
                              plays until ACTION_STOP / ACTION_SNOOZE / onDestroy
                                              │  cancel fade → player.stop/release → abandon focus
                                              │  → release wake lock → cancel notif → stopForeground

MainActivity ─ alarmFired ─→ EstadoAlarmas ─→ app.dart pushes PantallaAlarmaSonando (DISPLAY ONLY)
                                                    │ Stop / Snooze / back
                                                    ▼
                              finalizarEjecucion / posponerAlarma ─→ ocultarNotificacionAlarma
                                                    ▼
                              PluriWaveAlarmService.stop(activeId)  (native stop = the ONLY audio stop)
```

Layering / boundaries:
- Native (Kotlin): owns ALL ring audio, fade, focus, notification. No Dart audio dependency.
- Bridge (MethodChannel `pluriwave/alarm_scheduler`): loses `confirmFlutterAudio`,
  `overrideMediaVolumeForRing`, `restoreMediaVolume`. Keeps scheduling / dismiss / snooze / diagnostics.
- Dart port (`PuertoAlarmasAndroid`): loses the 3 handoff/override methods; screen is pure UI.
- Audio-focus mechanism (not app code) handles the user's normal radio: `AUDIOFOCUS_GAIN_TRANSIENT`
  transiently pauses `STREAM_MUSIC` playback; abandoning on stop lets it resume. The screen never
  touches `EstadoRadio` — the OS focus policy replaces the old manual pause/restore.

## 3. Component map and data flow

| Component | Change | Detail |
|-----------|--------|--------|
| `PluriWaveAlarmService.kt` | Rebuild | dB-curve fade (pure fn + single 50 ms loop, ring-anchored), manual focus, silent v3 channel, delete `flutterOwnsRing` + both backstop sites; keep wake lock / FGS-before-audio / 3-stage fallback / id-scoped stop verbatim |
| `MainActivity.kt` | Delete surface | remove `confirmFlutterAudio` / `overrideMediaVolumeForRing` / `restoreMediaVolume` handlers, private `overrideMediaVolumeForRing` / `restoreMediaVolume`, companion `mediaVolumeOverridden` / `capturedMediaVolume` / `restoreMediaVolumeBestEffort` |
| `pantalla_alarma_sonando.dart` | Rewrite → pure UI | delete all audio orchestration; keep single-exit guard, Stop/Snooze/back → EstadoAlarmas, PopScope, `_dismissScreen`, snooze options, layout |
| `app.dart` | Delete pre-start | remove `_prearrancarAudioAlarma` + call, `audioPrearrancado` arg, `_volumenInicialFadeInAlarmas`; keep SKIP/POSTPONE/PRE_NOTICE routing + duplicate-delivery guard |
| `servicio_alarmas_android.dart` | Reduce port | drop `confirmarAudioFlutter` / `forzarVolumenMediaParaAlarma` / `restaurarVolumenMedia` from interface + impl |
| `test/helpers/fakes_alarmas.dart` | Reduce fake | drop the 3 overrides + `volumenForzado` / `volumenRestaurado` / `puertaConfirmarAudioFlutter` / `fallaConfirmarAudioFlutter` |
| 4 test files | Rewrite/trim | see §7 |

## 4. Decisions (ADR)

### D1 — Fade as a pure function + one ring-anchored 50 ms Handler loop
**Decision.** Extract the DeskClock curve to a pure, side-effect-free function so the math is
inspectable and JVM-testable later:
```
private const val FADE_TICK_MILLIS = 50L
private const val FADE_RANGE_DB = 40.0f   // DeskClock: -40 dB → 0 dB ≈ 1% → 100% amplitude

fun computeFadeVolume(elapsedMs: Long, fadeMs: Long, ceiling: Float): Float {
    if (fadeMs <= 0L) return ceiling.coerceIn(0f, 1f)
    val fraction = (elapsedMs.toFloat() / fadeMs.toFloat()).coerceIn(0f, 1f)
    val gainDb = fraction * FADE_RANGE_DB - FADE_RANGE_DB          // -40..0 dB
    val curve = Math.pow(10.0, (gainDb / 20.0)).toFloat()          // 0.01..1.0
    return (ceiling * curve).coerceIn(0f, 1f)
}
```
A SINGLE `Handler` loop (50 ms tick) drives the whole ring, reading the current `player` field
each tick so it survives the 3-stage source swap. `ceiling = volume` (the per-alarm scalar, already
wired via `EXTRA_VOLUME`). At `fraction=0` → `ceiling*0.01`; at `fraction=1` → `ceiling`.
**Rejected.** (a) Per-source fade restarts (current shape) — a source swap would restart the
crescendo from 1% after the user already waited. (b) Linear-amplitude ramp (current `startFadeIn`)
— inaudible for the first half, the exact defect being fixed. (c) 250 ms tick — audibly stepped at
low gain where the ear is most sensitive; 50 ms is the DeskClock cadence.
**Replaces.** `startFadeIn`, `initialVolume`, `FADE_IN_STEP_MILLIS`, `FADE_IN_START_FRACTION`.

### D2 — Anchor the fade at RING start, not at audio start
**Decision.** Capture `fadeAnchorElapsedMs = SystemClock.elapsedRealtime()` once in `startAlarm`
(before audio). Every tick and every pre-start `setVolume` computes `elapsed = now - anchor`.
**Why.** Matches the on-device-proven behavior just shipped (commit 2e64740, "anchor the fade at
alarm time"): a slow-buffering station or a 15 s stage timeout must NOT freeze/restart the ring at
1%. When a source finally prepares, it joins the ramp at the elapsed level (a fresh source starting
at, e.g., 50% via `setVolume` before `start()` is click-free, not a pop).
**Rejected.** Pure DeskClock "anchor at crescendo/audio start" — reintroduces the long-buffer
freeze the app already fixed; the 3-stage fallback makes per-source anchoring user-hostile.
**Trade-off.** After a 15 s station timeout the WAV enters at a higher fade level; acceptable and
preferable to silence — the user has already waited in silence.

### D3 — Manual audio focus: `AUDIOFOCUS_GAIN_TRANSIENT`, version-guarded, no ducking listener
**Decision.** Request focus ONCE in `startAudio` (before the fallback chain, so it covers whichever
source plays); abandon in `stopAlarm`'s full-teardown branch (next to `releaseWakeLock`, NOT in the
mismatched-id early return). Use the modern API on O+ and the deprecated stream API below:
```
// O+ : AudioFocusRequest.Builder(AUDIOFOCUS_GAIN_TRANSIENT)
//        .setAudioAttributes(alarmAudioAttributes())   // USAGE_ALARM
//        .setOnAudioFocusChangeListener { }             // no-op: an alarm does not duck/stop
//        .build()  → store to abandon the exact request
// < O : requestAudioFocus(noopListener, AudioManager.STREAM_ALARM, AUDIOFOCUS_GAIN_TRANSIENT)
```
**Why.** ExoPlayer's auto-focus throws for non-media usages; DeskClock requests focus manually.
`TRANSIENT` (not `GAIN`) so the user's music/radio auto-resumes when we abandon. The listener is a
no-op because an alarm must keep ringing through focus changes.
**Rejected.** (a) No focus request — the user's `STREAM_MUSIC` radio keeps playing under the alarm
(the exact double-audio symptom, now solved by the OS instead of manual Dart pause). (b) Permanent
`GAIN` — music would not resume after dismiss.
**Note.** If `minSdk >= 26` the pre-O branch is dead code and may be dropped; the guard is kept
for correctness regardless.

### D4 — Silent channel `pluriwave_alarm_fire_v3` + single `channels_migrated_v3` migration
**Decision.** New channel id `pluriwave_alarm_fire_v3`, `IMPORTANCE_HIGH` (kept — required for FSI),
`setSound(null, null)` (silent: the player is the only audio). Replace the `channels_migrated_v2`
guard with ONE `channels_migrated_v3` guard that deletes all three obsolete ids
(`pluriwave_alarm_native`, `pluriwave_alarm_fire`, `pluriwave_alarm_fire_v2`) — `deleteNotificationChannel`
is a safe no-op when a channel is absent, so this is correct on both fresh installs and v2 devices.
Update the `CHANNEL_ID` constant and its single use in `buildNotification`.
**Why.** Android locks channel sound at creation; editing `_v2` (which set `DEFAULT_ALARM_ALERT_URI`)
is a no-op. A new id is the only way to make the fire notification silent. The v2 migration already
proved this pattern.
**Rejected.** Keeping both `_v2` and `_v3` migration guards — redundant; a folded `_v3` guard is
simpler and equally safe.
**Scope.** Only the ring channel resets user-visible settings; the pre-notice channel is untouched.

### D5 — Keep channel vibration ON (minimal change) rather than an explicit Vibrator
**Decision.** `enableVibration(true)` on `_v3`, as `_v2` had.
**Why.** DeskClock vibrates via a separate `Vibrator`, but adding one here expands surface for no
functional gain; the channel-level vibration already works. Minimal change wins.
**Rejected.** Explicit `Vibrator` with a pattern — more code, new permission/coordination surface,
out of proportion to the ring-audio goal. Can be a follow-up if per-alarm vibration control is wanted.

### D6 — Keep MediaPlayer; reject ExoPlayer/Media3 now
**Decision.** MediaPlayer stays for all three sources.
**Why.** It is already pop-free and already streams stations successfully. ExoPlayer has an
unresolved start-pop (#2752, ~200 ms at full gain) and would need muted-preroll mitigation.
**Rejected.** ExoPlayer/Media3 for ICY metadata + reconnect — real benefits, but not worth the pop
risk for the ring; revisit only if station reconnect proves insufficient on device.

### D7 — Kill the handoff surface entirely
**Decision.** Delete `flutterOwnsRing` (field, reset in `startAlarm`, both guard reads in
`stopAlarm`/`onDestroy`, and the companion doc); delete `MainActivity.restoreMediaVolumeBestEffort`
and its two call sites; delete the `confirmFlutterAudio`/`overrideMediaVolumeForRing`/`restoreMediaVolume`
handlers + private methods + companion state. On the Dart side delete the matching port methods,
service impls, and fake members.
**Why.** With one owner there is no handoff to signal and no stream to restore — "restore" is a
no-op by construction because no system volume is ever written. Every guard that existed to keep the
two owners from silencing each other becomes dead.
**Verification (this phase).** Grepped every reference; the only callers are the sites listed above.
Nothing else in the codebase reads/writes these symbols.

### D8 — Ring-state visibility: NO new channel; status from static alarm config
**Decision.** Do NOT add a native→Dart ring-state event. The screen's status line (currently the
tri-state `_fallbackActivo`/`_radioIntentada` text) is re-sourced from `widget.alarma` static config
(e.g. the configured station name when `alarma.emisora != null`, else a neutral ringing label). The
`Text` widget stays in place so the visual layout is unchanged.
**Why.** In native-only, Dart cannot know which source is playing without a new channel — which
would contradict "kill the handoff, minimal surface." The system notification already shows the
station name for "what's playing." Evidence: the only screen state that depended on live playback
was that one status line; everything else (time, name, buttons) is already static.
**Rejected.** (a) New ring-state EventChannel — reintroduces a cross-boundary protocol for a cosmetic
label. (b) Removing the line entirely — would alter the layout the proposal says to keep.
**Consequence.** l10n keys `alarmRingingFallbackActive` / `alarmRingingTryingStation` /
`alarmRingingPreparingFallback` become unused; leaving them is harmless (arb cleanup out of scope).

### D9 — Screen exit path unchanged; native stop is the only audio stop
**Decision.** Keep `_detener` → `finalizarEjecucion(id)` and `_posponer` → `posponerAlarma`, both of
which already route the native stop via `ocultarNotificacionAlarma`. `_detener`/`_posponer` no longer
touch `EstadoRadio` (no Flutter audio to stop; focus abandon handles the user's radio). Keep the
single-exit `_salidaEnCurso` guard, `PopScope(canPop:false)` back=Stop, `_dismissScreen`
(canPop→pop / else SystemNavigator.pop), snooze options, failure SnackBar (with the pre-captured
`ScaffoldMessenger`).
**Verification (this phase).** Traced `finalizarEjecucion`/`posponerAlarma` → `ocultarNotificacionAlarma`
→ `dismissAlarmNotification` → `PluriWaveAlarmService.stop(activeId)` → full-teardown branch. Confirmed
the active id stops; a different id only cancels its own notification.

### D10 — Keep `USAGE_ALARM + CONTENT_TYPE_MUSIC`
**Decision.** Leave `alarmAudioAttributes()` unchanged and reuse it for the focus request.
**Why.** `USAGE_ALARM` is the load-bearing part — it routes to `STREAM_ALARM`, making the ring
audible at media-volume 0 and uninterruptible. `CONTENT_TYPE` is secondary; MUSIC suits a station
and already works. Changing to `SONIFICATION` is optional and not worth the churn.

### D11 — Defer receiver wake-lock + OEM hardening to `oem-reliability-guidance`
**Decision.** Do NOT add a receiver-level `PARTIAL_WAKE_LOCK` or OEM autostart guidance in this
change. Verified `PluriWaveBootReceiver` already reschedules only (no boot FGS), so nothing to change
there.
**Why.** The proposal scopes this change to the AUDIO rebuild; delivery/OEM hardening is an explicit
downstream follow-up. Keeping them separate keeps this diff focused and revertible.

## 5. Integration points and do-not-touch verification

- Notification chains are INDEPENDENT: pre-notice + snooze-countdown live on `pluriwave_alarm_pre_notice`
  via `AlarmScheduler.ensurePreNoticeChannel`; `dismissFireNotification` only cancels the fire
  notification by id; `cancelAlarm` cancels pending intents + both notifications but never touches the
  ring player. The `_v2→_v3` bump cannot affect them.
- Snooze truth-ownership unchanged: native `ACTION_SNOOZE` still re-arms via `AlarmScheduler.snooze`
  and reports back through `notifyAlarmEvent`; `EstadoAlarmas._alRecibirEventoNativo` still records it.
  Killing the handoff does not touch any of these paths.
- Wake-lock / `startForeground`-before-audio ordering, 3-stage fallback with 15 s timeouts, and the
  id-scoped `stopAlarm` mismatch branch are preserved verbatim.

## 6. Data flow — teardown detail

```
Stop / Snooze / system-back  ─→ _detener / _posponer  (single-exit guard)
        │ finalizarEjecucion(id)  |  posponerAlarma(alarma, min)
        ▼
EstadoAlarmas ─→ android.ocultarNotificacionAlarma(id)  ─ MethodChannel dismissAlarmNotification
        ▼
PluriWaveAlarmService.stop(id) ─→ stopAlarm(id==active) ─→ cancel fade loop → player.stop()/release()
        → abandon audio focus → release wake lock → cancel fire notif → stopForeground → stopSelf
```
No stream restore, no Dart player teardown — there is nothing to undo.

## 7. Test design

Dart `flutter test` compiles the WHOLE test library as one unit: any file referencing a removed
symbol breaks the entire suite. This drives both the rewrite list and the work-unit split (§8).

Dies (compile-forced by port/param removal):
- `servicio_alarmas_android_test.dart`: DELETE the two tests `forzarVolumenMediaParaAlarma invoca
  overrideMediaVolumeForRing` (L110-122) and `restaurarVolumenMedia invoca restoreMediaVolume`
  (L124-136). Keep the scheduleAlarm-payload and battery tests.
- `pantalla_alarma_sonando_test.dart`: DELETE groups `rampa anclada y override diferido al primer
  audio` (L172-222) and `handoff con audio prearrancado ya reproduciendo (regresion)` (L224-246);
  DELETE `salir a mitad de rampa restaura la ganancia del reproductor` (L273-291) and `restore de
  volumen de medios con dispose como unico llamador` (L294-308). Remove the `audioPrearrancado` arg
  and the `audioYaReproduciendo` gate from `_montarPantalla`.
- `pantalla_alarma_sonando_dismiss_guard_test.dart`: DELETE group `media-volume override restore
  (Slice 2)` (L360-429). Remove `audioPrearrancado:true` from both mount helpers.

Rewritten as pure-UI (buttons → EstadoAlarmas, navigation, SnackBar; NO audio asserts):
- `pantalla_alarma_sonando_test.dart` KEEPS: snooze-options rendering (L126-148); `posponer 5 min`
  (L150-170) trimmed to assert `snoozeHasta` + `ocultadas contains id` + `programadas.last.snoozeHasta`
  + screen dismissed (drop `audio.pausas`); system-back = Stop (L248-271) trimmed to assert dismissed
  + `ocultadas contains id` (drop `audio.pausas`, drop `volumenForzado`).
- `pantalla_alarma_sonando_dismiss_guard_test.dart` KEEPS: dismiss-guard canPop/SystemNavigator group
  (L183-297) and snooze-failure SnackBar group (L299-358), unchanged except mount-helper signature.
- `pantalla_alarma_sonando_scaffold_test.dart`: unchanged asserts; only drop the `audioPrearrancado`
  arg. Both scaffold/animation tests survive.

Decoupling proof (reframed, KEEP): the `EstadoRadio ... nunca dispara el override de volumen`
regression (L431-445) can no longer assert `volumenForzado`/`volumenRestaurado` (removed). Reframe it
as: a normal `reproducir`/`pausar` cycle leaves the alarm port untouched (`programadas` / `detenidas`
/ `ocultadas` all empty). The strongest decoupling guarantee is now COMPILE-TIME: the fake no longer
HAS override methods, so no screen code can call them.

Fade math: `computeFadeVolume` is documented as a pure Kotlin function for inspection. No JVM harness
is added (Kotlin has none today). On-device QA checklist is the acceptance gate:
1. Audible exponential curve (not linear/late) at a configured fade of 15–30 s.
2. Volume ceiling correct: "50%" ≈ 50% of the device ALARM knob at full ramp.
3. No start pop on station, fallback station, and WAV.
4. No second audio source (native only; Dart plays nothing).
5. Dismiss / snooze / system-back all stop the ring and abandon focus (user's music resumes).
6. Media volume 0 still rings (USAGE_ALARM); ALARM stream 0 is silent (accepted).
7. Screen-off FSI delivery + ring after HyperOS Autostart enabled (POCO X7 Pro).

## 8. Work-unit split — 2 units, Dart-first (stacked-to-main)

The proposal suggested 3 units (Kotlin / Dart / tests). This design consolidates to **2**, and
reverses the order, with justification.

- **WU1 — Dart + fakes + tests (ONE unit).** `pantalla_alarma_sonando.dart`, `app.dart`,
  `servicio_alarmas_android.dart` (port+impl), `fakes_alarmas.dart`, and all 4 test files.
  *Why atomic:* removing `audioPrearrancado` and the 3 port methods breaks compilation of every test
  still referencing them; Dart test compilation is whole-suite, so the surviving tests cannot even
  run until the tests are rewritten in the SAME unit. Splitting "Dart lib" from "tests" is impossible
  for a green PR.
- **WU2 — Kotlin.** `PluriWaveAlarmService.kt` rebuild (dB curve, manual focus, silent v3 channel,
  delete `flutterOwnsRing` + backstops) and `MainActivity.kt` surface deletion. On-device QA gate.

**Order = Dart-first, and it matters.** Each stacked PR must be shippable:
- Dart-first intermediate (new pure-UI Dart + OLD native): the OLD native already plays the full ring
  via its 3-stage fallback until `stopAlarm`; new Dart calls none of the deleted handlers, so there is
  NO double audio and NO `notImplemented` exception. The ring works (old linear fade + the pre-existing
  channel-sound overlap; native on `STREAM_ALARM` so media-0 still rings). This is not worse than what
  is shipped at 2e64740 — it is better (the failed handoff is gone). SHIPPABLE.
- Kotlin-first intermediate (OLD Dart + new native) would be BROKEN: WU2 deletes the `MainActivity`
  handlers while old Dart still calls `confirmFlutterAudio`/override/restore → `confirmFlutterAudio`
  no longer stops the native, and old Dart simultaneously starts its `_fallbackPlayer`/radio ramp →
  DOUBLE AUDIO on device. Rejected.

Therefore: ship WU1 (Dart) first, WU2 (Kotlin) second. After WU2, no Dart code references the deleted
native handlers, so their removal is clean.

## 9. Risks and assumptions

| Risk / assumption | Severity | Mitigation |
|-------------------|----------|------------|
| Kotlin not agent-compilable | High | On-device QA checklist (§7) is the gate; fade math isolated in a pure fn for inspection |
| Focus request pauses user's radio but resume UX differs per OEM | Medium | `TRANSIENT` is the standard; verify resume on device (checklist #5) |
| `_v3` channel bump resets ring-channel settings for users | Low (expected) | Release note; pre-notice channel untouched; revert recreates `_v2` harmlessly |
| Dart-first intermediate shows old fade / channel-sound overlap briefly | Low | It is ≤ current shipped behavior; only exists between WU1 and WU2 |
| Anchor-at-ring-start makes WAV enter loud after a 15 s station timeout | Low | Intended (§D2); preferable to silence |
| Assumption: OS focus policy replaces manual radio pause on all target devices | Medium | Validate on POCO X7 Pro; fallback is a follow-up, not a blocker |