pluriwave/openspec/changes/app-quality-and-native-alarms/design.md

Design: app-quality-and-native-alarms

Technical design for the seven chained slices that raise PluriWave to native-Android-Clock alarm reliability, fix the snooze divergence, harden the audio/runtime layer, add streaming resilience, split the EstadoRadio god-class, and close the design-system / a11y / i18n / quality-gate gaps. The custom native alarm stack is KEPT and hardened. Every decision below is grounded in the actual code (file:line) so sdd-tasks can act without re-discovery.

This document is the HOW at the architectural level. It does not enumerate task steps (that is sdd-tasks). flutter build is FORBIDDEN; Kotlin is verified on-device by the user. Strict TDD applies via flutter test.

Architecture at a glance

Layer	Owns	Key files
Flutter domain	Alarm data, recurrence math, persistence, single source of truth for snooze state	servicio_alarmas.dart, servicio_programacion_alarmas.dart, estado_alarmas.dart
Flutter audio	Radio playback, EQ, recording, reconnect-on-stall, audio focus	servicio_audio.dart (PluriWaveAudioHandler), new ServicioAudioSession
Flutter UI	Ringing screen, editor, mini player, screens	pantalla_alarma_sonando.dart, pantalla_alarmas.dart, mini_reproductor.dart
Bridge	MethodChannel pluriwave/alarm_scheduler (Flutter↔native), alarmFired callback (native→Flutter)	servicio_alarmas_android.dart, MainActivity.kt
Native delivery	Exact wakeup (setAlarmClock), FSI notification, native audio + fade, snooze reschedule	AlarmScheduler.kt, PluriWaveAlarmReceiver.kt, PluriWaveAlarmService.kt, AndroidManifest.xml

The guiding principle for this change: the Flutter ServicioAlarmas config is the single source of truth for "postponed until". Native reschedules autonomously for wakeup reliability, but every native state mutation that changes the next occurrence MUST be reflected back to Flutter through the bridge so the two never diverge. Slice 2 establishes that protocol; the current divergence is the root cause of the user-reported broken snooze.

---

Slice 1 — Alarm native reliability (CRITICAL)

Decision 1.1 — Foreground-service type and permission (A1)

• Manifest: change PluriWaveAlarmService to android:foregroundServiceType="mediaPlayback|alarm" (AndroidManifest.xml:54-57). Add <uses-permission android:name="android.permission.FOREGROUND_SERVICE_ALARM"/> next to the existing FOREGROUND_SERVICE_MEDIA_PLAYBACK (AndroidManifest.xml:5).
• Service: when calling startForeground (PluriWaveAlarmService.kt:75), on API ≥ 34 pass the explicit type bitmask ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK or ServiceInfo.FOREGROUND_SERVICE_TYPE_ALARM via the 3-arg startForeground(id, notification, type) overload. On API < 34 keep the 2-arg overload.
• Rationale: include BOTH types because the service plays a radio stream (mediaPlayback) AND is an alarm (alarm). The alarm type is the one that satisfies the API 34+ FGS-launch-from-background restriction when started from PluriWaveAlarmReceiver.onReceive (PluriWaveAlarmReceiver.kt:27). Alarm-triggered broadcasts receive a temporary FGS-while-in-use exemption, so starting an alarm-typed FGS from the fire receiver is the documented, allowed path on API 34+.
• ADR note (rejected): using only mediaPlayback keeps the silent-failure bug; using only alarm would block the legitimate media-playback path the radio stream needs. KEEP both.

Decision 1.2 — Single FSI notification, ownership and ordering (A3)

Today two notifications fire for one event: the receiver posts fireNotificationIdForAlarm (PluriWaveAlarmReceiver.kt:95-133) AND the service posts NOTIFICATION_ID 92841 via startForeground (PluriWaveAlarmService.kt:75). dismissFireNotification only cancels the receiver's (AlarmScheduler.kt:304-308), leaving the service's orphaned.

• Decision: the service's startForeground notification (NOTIFICATION_ID 92841) is the single owner of the ringing FSI. Remove showFireNotification from the receiver entirely (PluriWaveAlarmReceiver.kt:37, 95-133).
• Ordering problem: an FSI must appear immediately, even before the radio stream prepares (prepareAsync is async, ~seconds). The service already calls startForeground synchronously at the top of startAlarm BEFORE startAudio (PluriWaveAlarmService.kt:75 then :83). That notification carries setFullScreenIntent(...) (add it to buildNotification, currently the service builder has it at :267). So the FSI shows the instant the service enters foreground, audio attaches afterward — correct ordering, no gap.
• The receiver still does context.startActivity(launch) (PluriWaveAlarmReceiver.kt:38-43) to bring the Flutter ringing screen forward; that is the activity launch, not a notification, so no duplication.
• Cleanup: stopAlarm must cancel NOTIFICATION_ID 92841 through stopForeground(STOP_FOREGROUND_REMOVE) (already at :242) and ALSO cancel any legacy fireNotificationIdForAlarm id for installs upgrading mid-ring (:236-240 already does this — keep it as a migration safety net for one release).
• fireNotificationIdForAlarm helper stays (referenced by cancelAlarm AlarmScheduler.kt:300) but is no longer posted to.

Decision 1.3 — Channel sound versioning to apply USAGE_ALARM (A4)

Android locks setSound(uri, attributes) at channel creation; the existing channels pluriwave_alarm_native (PluriWaveAlarmService.kt:374) and pluriwave_alarm_fire (PluriWaveAlarmReceiver.kt:269) were created without sound, so editing them in place is a no-op on existing installs.

• Decision: channel versioning. Introduce versioned channel ids and delete the old ones once:
  • New ringing channel: pluriwave_alarm_fire_v2 (IMPORTANCE_HIGH) with setSound(<bundled-alarm-uri>, alarmAudioAttributes) and enableVibration(true). This is the channel the service's startForeground notification uses.
  • Keep the pre-notice channel id but bump only if its config changes; it stays silent (setSound(null, null), PluriWaveAlarmReceiver.kt:232) so no version bump needed.
  • Consolidate to TWO channels total (A8): the ringing channel (_fire_v2) and the pre-notice channel. The service stops using its own pluriwave_alarm_native channel and posts on _fire_v2.
• Sound URI: a Settings.System.DEFAULT_ALARM_ALERT_URI (system default alarm tone) is the channel-level sound for the heads-up/locked alert. Note the bundled WAV played by MediaPlayer (PluriWaveAlarmService.kt:355-362) is the AUDIO that loops; the channel sound is the notification-attached alert. They are distinct; channel sound exists so even if the service audio fails the channel still produces an alarm-attributed sound. Use USAGE_ALARM AudioAttributes on both.
• Migration: add a one-time deletion of the obsolete channels (pluriwave_alarm_native, pluriwave_alarm_fire) via manager.deleteNotificationChannel(...) guarded by a SharedPreferences flag channels_migrated_v2 so it runs once and does not reset the user's settings on the new channel repeatedly. Deleting a channel and recreating under a NEW id is the only way Android lets you change locked sound settings without the user manually clearing data.
• ADR note (rejected): mutating the existing channel in place — Android ignores setSound after creation, so it would silently keep the bug.

Decision 1.4 — emisoraFallback passthrough and second prepare attempt (A5)

Today programar() sends stationName/stationUrl/fallbackSound but NEVER emisoraFallback (servicio_alarmas_android.dart:167-173); the Kotlin NativeAlarmSpec has no fallback-station field. The native fallback is only the bundled WAV.

• Bridge payload: add fallbackStationName and fallbackStationUrl to the scheduleAlarm MethodChannel args in programar() (servicio_alarmas_android.dart:148-174), sourced from alarma.emisoraFallback.
• Kotlin model: add fallbackStationName: String? and fallbackStationUrl: String? to NativeAlarmSpec (AlarmScheduler.kt:571-648), to toJson (bump schemaVersion 2→3 at :594) and fromJson (:618-646, read with optString(...).takeIf { isNotBlank() }). Wire through scheduleAlarm(...) signature (AlarmScheduler.kt:21-40) and the MainActivity handler (MainActivity.kt:68-106). Add the two extras to EXTRA_* constants and the fireIntent extras (PluriWaveAlarmReceiver.kt:277-279, AlarmScheduler.kt:487-507).
• Service audio chain: extend startAudio (PluriWaveAlarmService.kt:86-108) to a three-stage ordered fallback:
  1. Primary station: startStationAudio(primary) with a 15s timeout (STATION_START_TIMEOUT_MILLIS already 15s at :379).
  2. On primary timeout/error/completion → fallback station (if present): a SECOND prepareAsync against fallbackStationUrl, again with a 15s timeout.
  3. On fallback-station timeout/error (or absent) → bundled WAV (startFallbackAudio, :162).
  • Implement as a small state machine: pass the next-stage lambda into the prepared/error/completion/timeout handlers instead of jumping straight to the WAV. Reuse scheduleStationFallback per stage with its own runnable so the 15s windows are independent and cancelStationFallback clears the current stage.
• Persisted-spec migration: already-scheduled alarms have schemaVersion: 2 specs in device-protected SharedPreferences (AlarmScheduler.kt:436-444). fromJson must default the two new fields to null when absent (no fallback station) — additive and backward compatible. On the next Flutter programar() (boot resync via reschedulePersistedAlarms :315 or app open via _sincronizarTodas estado_alarmas.dart:286-296) the v3 fields are written. No destructive migration needed.

Decision 1.5 — Native fade-in honoring fadeInSegundos (A6)

The native service plays at constant volume (PluriWaveAlarmService.kt:120-121, 176-177). The Dart screen fade (pantalla_alarma_sonando.dart:92-115) only runs when the screen is foregrounded.

• Bridge: add fadeInSegundos to the scheduleAlarm payload (servicio_alarmas_android.dart) and to NativeAlarmSpec (default 0). AlarmaMusical.fadeInSegundos already exists (used at pantalla_alarma_sonando.dart:96).
• Service: implement a MediaPlayer.setVolume ramp in the service driven by the existing mainHandler (PluriWaveAlarmService.kt:27). On the setOnPreparedListener start (:128-136 and the fallback :179-183), if fadeInSegundos > 0, start at a low floor (e.g. 0.05 * target) and step every 250 ms toward volume over fadeInSegundos, mirroring the Dart algorithm (pantalla_alarma_sonando.dart:101-114). Cancel the ramp runnable in stopAlarm (:224) and on snooze.
• Coordination with the Dart fade: when the ringing screen is foregrounded with native audio already ramping, the screen must NOT double-ramp. The screen owns the fade ONLY for its own _fallbackPlayer and the radio.audio it pre-started; the native service owns the fade for native MediaPlayer audio. They never play the same source simultaneously (service stops when Flutter confirms audio via confirmFlutterAudio, MainActivity.kt:139-148). Document this hand-off boundary in the service header comment.

Decision 1.6 — Battery-optimization request placement (A7)

REQUEST_IGNORE_BATTERY_OPTIMIZATIONS is declared (AndroidManifest.xml:13) and diagnostico.ignoraOptimizacionBateria is read (servicio_alarmas_android.dart:65) but never requested.

• Decision: add a native requestIgnoreBatteryOptimizations MethodChannel method in MainActivity (mirror requestExactAlarmPermission :255-270) that launches Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS with package: data. Add solicitarExencionBateria() to PuertoAlarmasAndroid / ServicioAlarmasAndroid (servicio_alarmas_android.dart:93-107, 196-218).
• Placement and prompt-fatigue guard: call it inside _solicitarPermisosNecesariosParaAlarma (estado_alarmas.dart:268-284) ONLY when !diag.ignoraOptimizacionBateria AND an asked-once flag is unset. Persist the flag (bateria_exencion_solicitada) in the injected SharedPreferences (Slice 3). Request once; never re-prompt automatically. The user can re-request from the diagnostics UI manually.
• ADR note: requesting on every guardarAlarma (which calls this method, estado_alarmas.dart:87) would spam the user. The asked-once flag is mandatory.

Slice 1 size note

Kotlin (manifest + service FGS type + channel v2 + 3-stage fallback + fade ramp) + Dart bridge (payload fields + battery method) ≈ 300-340 lines. Within budget. Native edits are surgical and mirror existing patterns to minimize compile risk.

---

Slice 2 — Alarm UX parity and SNOOZE CORRECTNESS (HIGH)

Snooze audit — found defects (file:line)

The user reports snooze did not work correctly. Root cause is state divergence between the native scheduler and the Flutter source of truth, plus inconsistent snooze anchoring. Precise findings:

#	Defect	Evidence	Effect
S1	The native ringing-notification snooze (ACTION_SNOOZE) reschedules natively then stopAlarm(), and NEVER notifies Flutter. The alarmFired callback only fires from MainActivity.onNewIntent on an activity launch (MainActivity.kt:227-234); the snooze service path starts no activity.	PluriWaveAlarmService.kt:42-49 → AlarmScheduler.snooze() → stopAlarm(); no startActivity; MainActivity.kt:233 never reached.	Flutter EstadoAlarmas keeps the OLD next-occurrence; native fires at the snoozed time. UI shows wrong "next alarm"; reconciliation only happens on the next 60s refrescarProgramacion (estado_alarmas.dart:316), which RECALCULATES from scratch and can lose the native snooze. Divergence.
S2	Two different snooze anchors in native code. snooze() uses now + minutes (AlarmScheduler.kt:257); postponeNext() uses occurrenceAt + minutes clamped to now (AlarmScheduler.kt:270-273).	AlarmScheduler.kt:254-287	Snooze-from-ringing and snooze-from-pre-notice land at different times for the same intent. Inconsistent with Flutter posponerEjecucion which uses calcularSnooze(now, minutos) (servicio_alarmas.dart:262).
S3	The ringing screen has NO snooze button at all — only "Detener" (_detener). The only ringing-time snooze is the notification action, which is the S1-broken path.	pantalla_alarma_sonando.dart:200-204	User cannot snooze from the screen; if they snooze from the notification, S1 divergence triggers.
S4	refrescarProgramacion calls servicio.recalcularTodas() which runs _recalcular → clears snooze when !snoozeActivo and recomputes proximaEjecucion ignoring any native-only snooze.	estado_alarmas.dart:98-107, servicio_alarmas.dart:159-172, 378-397	A native snooze that Flutter never recorded (S1) is erased by the next periodic recalculation; native and Flutter then disagree on the next trigger.
S5	preserveNativeSnooze (AlarmScheduler.kt:342-357) only preserves a native snooze when Flutter reschedules WITHOUT a snooze and the origin matches requestedTriggerAtMillis. After S4 erases Flutter's snooze and recalculates a new trigger, the origin no longer matches, so preservation fails and the native snooze is dropped on the next programar().	AlarmScheduler.kt:347-356	The one safety net for divergence is defeated by the recalculation in S4.

Decision 2.1 — Single source of truth + native→Flutter snooze sync protocol

• Flutter ServicioAlarmas config is the canonical "postponed until" (snoozeHasta / snoozeOrigen on AlarmaMusical, written by posponerEjecucionHasta, servicio_alarmas.dart:266-294). Native is a mirror that must report back.
• New native→Flutter event: when the service handles ACTION_SNOOZE (PluriWaveAlarmService.kt:42-49), after AlarmScheduler.snooze(...), fire the alarmFired MethodChannel callback with a new action snoozed carrying alarmId, occurrenceAtMillis (the snooze origin) and snoozeUntilMillis. Because the service has no activity, route it through the EXISTING alarmMethodChannel held by MainActivity: expose a static MainActivity.notifyAlarmEvent(map) that invokes alarmMethodChannel?.invokeMethod("alarmFired", map) on the main thread when the engine is alive; if the engine is dead, the native snooze is already persisted and Flutter will reconcile on next launch via the handled-occurrences sync (extended below). This avoids inventing a second channel.
• Flutter side: ServicioAlarmasAndroid._instalarHandler (servicio_alarmas_android.dart:269-285) already forwards alarmFired events. Extend EventoAlarmaAndroid to carry the action snoozed. EstadoAlarmas listens (wire a subscription in inicializar) and on a snoozed event calls servicio.posponerEjecucionHasta(alarmId, occurrence, snoozeUntil) + _aplicar + notifyListeners — WITHOUT calling android.programar() again (native already scheduled it). This makes Flutter record the snooze native chose, killing S1.
• Extend the launch-on-snooze reconciliation: the native already persists snooze in its spec. Add snoozeUntilMillis/snoozeOriginMillis to getHandledAlarmOccurrences OR add a new getNativeSnoozeState method so _sincronizarEjecucionesGestionadasPorAndroid (estado_alarmas.dart:251-266) also imports active native snoozes on cold start. This covers the engine-dead case in the previous bullet.

Decision 2.2 — Unify the snooze anchor (fixes S2, S4, S5)

• Make native snooze() use the SAME anchor as postponeNext(): occurrenceAt + minutes where occurrenceAt = snoozeOriginMillis ?: triggerAtMillis, clamped to now + minutes if already past (AlarmScheduler.kt:254-265 adopts :270-273 logic). One snooze semantic everywhere, matching the Flutter posponerEjecucionHasta(ejecucion = snoozeOrigen ?? proximaEjecucion) anchor (estado_alarmas.dart:165-167).
• Guard recalcularTodas against erasing an active snooze: _recalcular already preserves snooze when snoozeActivo (servicio_alarmas.dart:384-385, 395). The real fix is S1/S4 — once Flutter RECORDS the native snooze (Decision 2.1), snoozeActivo is true and recalcularTodas preserves it. So S4/S5 are resolved transitively by 2.1. Keep preserveNativeSnooze as a belt-and-suspenders net.

Decision 2.3 — End-to-end snooze from the ringing screen (fixes S3)

• Add snooze buttons to PantallaAlarmaSonando (pantalla_alarma_sonando.dart:200-204 area): 3 / 5 / 10 plus the alarm's configured default (alarma.snoozeMinutos). A _posponer(int minutos) handler that mirrors _detener (:132-143) teardown: cancel _fallbackTimer, _fadeInTimer, _estadoSub; stop _fallbackPlayer; pause radio.audio; then await context.read<EstadoAlarmas>().posponerAlarma(widget.alarma, minutos); then navigator.pop().
• posponerAlarma already exists and does the right Flutter-first sequence: hides the native notification, records posponerEjecucion, re-programs native (estado_alarmas.dart:165-183). This is the CANONICAL path — the screen uses it, so Flutter is always the writer and native is the mirror. No divergence by construction.
• Teardown coordination: _fadeInTimer and _fallbackPlayer MUST be torn down before posponerAlarma re-programs native, otherwise the Dart fallback keeps looping after snooze. Add the same teardown to a shared private _liberarAudioLocal() used by both _detener and _posponer.

Decision 2.4 — Ringing screen redesign (C1, C3)

• Migrate from raw Scaffold (pantalla_alarma_sonando.dart:158) to PluriWaveScaffold. Replace hardcoded Color(0xFF061722) (:159) and Color(0xFFFFB86B) (:167) with PluriWaveTokens from the theme extension.
• Entry animation: wrap the glass surface content in a flutter_animate fade+scale entry, gated by the reduced-motion guard from Slice 5 (PluriAnimate extension). Do NOT introduce a Hero here (Hero work is C2, deferred/optional in Slice 5).
• BackdropFilter perf note: PluriGlassSurface uses BackdropFilter. On a cold GPU wake (screen-off → FSI), the first frame can stutter. Mitigation: render a cheap solid/gradient placeholder for the first ~1 frame, then enable the blur after the first addPostFrameCallback, OR cap the blur sigma on this screen. Document the constraint; keep the blur optional behind the reduced-motion guard so accessibility users also skip the expensive filter.

Decision 2.5 — Editor improvements (C7)

• Next-trigger preview inside _EditorAlarmaSheet (pantalla_alarmas.dart:387-636): compute via the existing ServicioProgramacionAlarmas.calcularProxima against the in-progress alarm draft and render a localized "Next: <date/time>" line. Reuse the Slice 5 locale-aware DateFormat.
• Searchable station picker: replace the DropdownButtonFormField with a bottom-sheet using SearchBar over the user's favorites (and optionally recent stations). Returns the selected Emisora for both primary and fallback fields. This also surfaces emisoraFallback selection in the UI, which Slice 1 now honors natively.
• Configurable snooze duration field: a segmented/slider control writing alarma.snoozeMinutos (sanitized to 3/5/10 to match native sanitizeSnoozeMinutes). Lower the volume-slider floor from 0.25 toward 0 (proposal scope).

Slice 2 size note

Snooze sync (bridge event + EstadoAlarmas listener + native callback + anchor unify) ≈ 120 lines; ringing screen redesign + buttons ≈ 130; editor (preview + picker + snooze field) ≈ 130. Total ≈ 380, AT the budget ceiling. Risk: may exceed 400. Proposed sub-split if the forecast trips the guard: 2a = snooze correctness (audit fixes 2.1–2.3, ringing buttons) and 2b = editor + visual redesign (2.4–2.5). 2a is the user-trust fix and ships first.

---

Slice 3 — Audio / runtime robustness (test seams) (HIGH)

Decision 3.1 — audio_session integration (B1)

• Add a ServicioAudioSession wrapper around package:audio_session (already in pubspec :19). Configure on app init with AudioSession.instance → configure(AudioSessionConfiguration.music()) adjusted: AVAudioSessionCategory.playback, AndroidAudioAttributes(usage: media, contentType: music), androidAudioFocusGainType: gain, androidWillPauseWhenDucked: true.
• Hook point: inside PluriWaveAudioHandler (servicio_audio.dart:113-147) or a thin collaborator it owns. Subscribe to:
  • interruptionEventStream: on begin with AudioInterruptionType.pause (phone call) → pause and remember "was playing"; on begin with duck → lower volume; on end with shouldResume → resume. This is what makes calls pause the radio (the missing B1 behavior).
  • becomingNoisyEventStream (headphones unplugged) → pause.
• Interaction with reconnect (Slice 7): an audio-session pause is a USER-INTENT pause-equivalent and MUST set the same "intentional pause" flag the reconnect logic checks (Decision 7.2), so the stall detector does not fight the interruption handler and try to reconnect during a phone call.
• Alarm path: the native alarm uses USAGE_ALARM and its own MediaPlayer, independent of this media session, so audio focus for the radio does not interfere with native alarm audio.

Decision 3.2 — Kill static state in ServicioAlarmasAndroid (B2)

• Convert static _eventosController, static _handlerInstalado, static _l10n (servicio_alarmas_android.dart:117-120) to INSTANCE fields. Install the handler in the constructor per instance.
• Make the channel injectable (the constructor already accepts MethodChannel, :110-112) and the localizations injectable per instance instead of a static setter. EstadoRadio.configurarLocalizaciones (estado_radio.dart:70-75) currently calls the static ServicioAlarmasAndroid.configurarLocalizaciones; rewire it to call the instance held by EstadoAlarmas.android. This makes the service unit-testable with a TestDefaultBinaryMessenger and removes global shared state.
• Backward-compat: keep a deprecated static shim for one release if other call sites reference it (grep shows only estado_radio.dart:74).

Decision 3.3 — Move configurarLocalizaciones out of build() (B3)

• MiniReproductor.build() calls configurarLocalizaciones(l10n) every rebuild (mini_reproductor.dart:23), firing on every buffer notification. Move it to didChangeDependencies (fires when locale/inherited widgets change, not on every notifyListeners), guarded so it only re-runs when the Locale actually changes. Convert MiniReproductor to StatefulWidget if needed, or hoist the call to a top-level locale listener in app.dart that runs once per locale change.

Decision 3.4 — Inject a single cached SharedPreferences (B4)

• Resolve SharedPreferences.getInstance() ONCE at startup (in main.dart) and inject the instance into ServicioAlarmas (constructor already accepts prefs, servicio_alarmas.dart:23-29), ServicioEcualizador, ServicioGrabacionRadio, and any service doing getInstance() (25+ sites per B4). Provide a backward-compatible default (_resolverPrefs already falls back to getInstance(), :399-400) so partial adoption stays functional and a revert is safe.
• This is also a test seam: tests pass SharedPreferences.setMockInitialValues({}) once.

Decision 3.5 — Guard recalcularTodas writes + single-writer cache (B5, B6, B9)

• recalcularTodas writes SharedPreferences unconditionally every minute (estado_alarmas.dart:316-318 → servicio_alarmas.dart:159-172). Add a dirty-check: compute the new config, compare serialized JSON (or a change flag from _recalcular) against the loaded config, and only _guardar when something changed. Returns the loaded config unchanged when clean (mirror the sincronizarEjecucionesNativas huboCambios pattern, :181, 219).
• In-memory cache + single-writer mutex in ServicioAlarmas to kill the read-modify-write N+1 race (B6): cargar() runs before every mutation (:86, 111, 124, 160, 179, 230, 271, 300) with no cache and no serialization, so concurrent guardarAlarma/posponer/refrescar interleave and lose writes. Decision: hold an in-memory ConfiguracionAlarmas? cache, hydrate on first cargar, and serialize ALL mutations through a single Future-chain mutex (the same pattern PluriWaveAudioHandler._colaCambioFuente uses, servicio_audio.dart:125, 282-285). Every mutation = await _lock → read cache → mutate → persist → update cache → release. This is THE seam the Slice 6 concurrency test exercises.
• Bound _ejecucionesEmitidas (estado_alarmas.dart:32): replace the unbounded Set<String> with a bounded LRU (cap ~200) or prune entries older than a day on each _vigilarAlarmasVencidas pass (:326-348). Keys are alarmId:millis; prune by parsing the millis suffix.

Decision 3.6 — Tame empty catch + unawaited (B7, B10) — scoped

• Not the focus of Slice 3 structurally, but where the seams touch servicio_audio.dart empty catches (:343, 346, 406, 428, 448) and app.dart:324 unawaited(radio.reproducir), replace silent swallow with at least a developer.log. Full lint enforcement is Slice 6 (unawaited_futures). Keep edits minimal here to stay under budget.

Slice 3 size note

Audio session ≈ 90, statics→instance + l10n rewire ≈ 70, prefs injection ≈ 60, dirty-guard + cache/mutex + bounded set ≈ 120, logging touch-ups ≈ 30. Total ≈ 370. Within budget but tight; if it trips, split 3a = test seams (statics, prefs, cache/mutex, dirty-guard) and 3b = audio_session + becoming-noisy. 3a unblocks Slice 6 tests; 3b is the call-pause feature.

---

Slice 7 — Streaming resilience (NEW, user request) (MEDIUM-HIGH)

Radio streams should survive short connection drops (seconds) via buffering and auto-recover.

Decision 7.1 — just_audio buffer configuration for LIVE streams

• just_audio ^0.9.42 supports AudioLoadConfiguration(androidLoadControl: AndroidLoadControl(...)), applied at AudioPlayer construction (servicio_audio.dart:159-163 _crearPlayer). Set:
  • minBufferDuration: 15s, maxBufferDuration: 50s — pre-roll the player keeps; larger min buffer absorbs jitter.
  • bufferForPlaybackDuration: 2.5s, bufferForPlaybackAfterRebufferDuration: 5s — how much must buffer before (re)starting playback; higher after-rebuffer value reduces re-stutter.
  • targetBufferBytes, prioritizeTimeOverSizeThresholds: true.
• Achievable window — be honest: for LIVE icy/HTTP radio there is NO seekable rewind window; the stream is unbounded and not stored to disk by default. The buffer is a forward jitter cushion, not a rewind history. So:
  • What we CAN achieve: tolerate network jitter / micro-drops up to roughly the maxBufferDuration worth of already-buffered audio (realistically a few to ~15-30 seconds of cushion depending on bitrate and how full the buffer was when the drop hit), and FAST automatic re-prepare when the connection returns.
  • What we CANNOT achieve: pause-and-resume across a long outage without a gap (live audio advances in real time; on reconnect you rejoin the live edge, not where you dropped). We do not promise gap-free recovery for outages longer than the buffered cushion.
• Decision: the realistic goal is jitter tolerance + fast recovery to the live edge, with a clear "reconnecting" UI state, not seamless time-shift. State this in the spec acceptance criteria so expectations are honest.

Decision 7.2 — Reconnect-on-stall with bounded exponential backoff

• Stall vs user-pause discrimination: track an explicit _intencionReproducir (intent-to-play) flag, set true on play/reproducir/reanudar and false on pause/stop and on an audio-session interruption pause (Decision 3.1). A STALL is: _intencionReproducir == true AND playerStateStream reports processingState == buffering for longer than a threshold (e.g. 8-10s) OR an error event arrives (servicio_audio.dart:189-194 _eventosSub.onError, currently routes to _gestionarErrorReproduccion).
• Reconnect loop in PluriWaveAudioHandler: on detected stall, instead of going straight to terminal error (_gestionarErrorReproduccion, :207-236), enter a reconnect state machine:
  • Surface a new EstadoReproduccion.reconectando (extend the enum servicio_audio.dart:14) so mini player / player UI shows "reconnecting".
  • Re-issue the source (_player.setUrl(mediaItem.id) then play) using the existing revision-guarded _cambiarFuente machinery (:288-332) so a user source-switch during reconnect cancels it (revision mismatch).
  • Bounded exponential backoff: delays 1s, 2s, 4s, 8s, 16s, 32s, then cap; total window ~60-90s (configurable max attempts ~7-8). After exhaustion, fall through to the EXISTING terminal _gestionarErrorReproduccion with the friendly message. This preserves current error UX as the final state.
  • Cancel/reset the backoff and counter on successful ready+playing, on user stop/pause, and on source switch.
• Interaction with EQ/volume/recording: reconnect re-creates the player via _recrearPlayer (:334-354) which already re-applies _volumen (:352) and re-activates the EQ (_activarEcualizador, :306, 372-383). Recording (ServicioGrabacionRadio) reads the live PCM/visualizer; on reconnect the androidAudioSessionId changes (re-emitted at :196-203) and recording/visualizer resubscribe via the existing session-id stream — no extra wiring needed, but the design MUST verify recording survives a session-id change (Slice 6 recording-recovery test covers it).
• Interaction with the alarm pre-start path (app.dart:316-325 _prearrancarAudioAlarma): when the alarm pre-starts the radio and the stream stalls, reconnect should engage normally, BUT the alarm screen already has its own 12s station timeout → bundled-WAV fallback (pantalla_alarma_sonando.dart:74-79). Decision: during an active alarm ring, the alarm's fallback timer takes precedence — if the radio has not reached reproduciendo within the alarm's timeout, the alarm switches to the bundled fallback regardless of reconnect attempts, because waking the user reliably beats reconnect persistence. The reconnect loop must not extend the alarm wake-up window. Expose enough state for the alarm screen to make that call (it already listens to estadoStream; reconectando must NOT be misread as reproduciendo).

Slice 7 size note

Buffer config ≈ 25, reconnect state machine + enum + backoff ≈ 180, UI "reconnecting" wiring in mini/player ≈ 60, alarm-path guard ≈ 20. Total ≈ 285. Within budget. Depends on Slice 3 (audio-session intent flag) landing first.

---

Slices 4-6

Slice 4 — EstadoRadio god-class split (HIGH, broad)

EstadoRadio (1121 lines, estado_radio.dart) owns 6 services + direct I/O (:30-62). Split seams and EXTRACTION ORDER (lowest-coupling first so each PR stays small and backward-compatible):

1. ServicioExportImport — extract the backup/import jsonDecode/jsonEncode from pantalla_ajustes.dart (1391 lines) AND any export logic in EstadoRadio. Pure logic, highest test value (round-trip), zero UI coupling. Extract FIRST.
2. EstadoEcualizador (ChangeNotifier) — EQ preset/active/band state currently proxied through EstadoRadio to audio/servicioEcualizador. Self-contained.
3. EstadoGrabacion (ChangeNotifier) — recording state + _escucharGrabacion subscription (estado_radio.dart:51, :79).
4. EstadoBusqueda (ChangeNotifier) — search results/query state.

• Provider wiring: register the new notifiers in the existing MultiProvider (alongside EstadoRadio). Use ProxyProvider where a notifier needs ServicioAudio from EstadoRadio, OR pass the shared service instances at construction.
• Migration strategy keeping each PR <400 lines: KEEP backward-compatible getters on EstadoRadio that delegate to the new notifiers during the transition, so screens compile unchanged. Migrate consuming screens to context.select/Consumer scopes (B11: pantalla_inicio.dart:43 root watch + 6 sites in pantalla_ajustes) in the SAME or a follow-up PR.
• Confirmed 4a/4b split (the proposal flags it; forecast WILL exceed 400 lines for all four extractions + rewiring):
  • 4a = ServicioExportImport + EstadoEcualizador extraction with backward-compatible getters (no screen rewiring yet). ≈ 350 lines.
  • 4b = EstadoGrabacion + EstadoBusqueda extraction + context.select rewiring of PantallaInicio/Ajustes/Favoritos + removal of the temporary getters. ≈ 380 lines.
• ADR note: a big-bang single PR would blow the budget and the blast radius; the getters-bridge keeps each PR independently revertible (proposal rollback plan).

Slice 5 — Design system, a11y, i18n (LOW, parallelizable)

• Color tokens: replace the 14+ Color(0x...) literals (explore C3 sites) with PluriWaveTokens from the theme extension. The ringing screen literals are migrated in Slice 2 (Decision 2.4); the rest here.
• A11y: Semantics(button: true, label: ...) on the 36x36 favorite InkWell (tarjeta_emisora.dart:238-289, also enlarge tap target toward 48dp), semanticLabel on _AssetIcon and alarm images (C4, C5).
• Reduced-motion guard — PluriAnimate extension design: a Dart extension on Widget (e.g. extension PluriAnimate on Widget) exposing pluriFadeIn(...), pluriScaleIn(...) etc. Each method reads MediaQuery.maybeDisableAnimationsOf(context) (or MediaQuery.of(context).disableAnimations); when true it returns the child UNANIMATED (or with duration zero), otherwise it applies the flutter_animate effect. Centralizes C6 so every entry animation (including the Slice 2 ringing screen) respects the OS reduced-motion setting through ONE call site. Requires a BuildContext, so it is a method taking context rather than a pure getter.
• i18n: locale-aware _fechaCorta via intl DateFormat.yMd(localeName) (pantalla_alarmas.dart:1114, fixes C8 for ja/en-US/ar). Pluralization for bare counters via ARB plural messages (pantalla_favoritos.dart:138, C9).
• Polish: rounded shimmer corners + shimmer in PantallaBuscar (C10, C11), _rounded icon variants (C12), brand notificationColor in main.dart:23 (C13).

Slice 6 — Quality gates (LOW, mostly tests)

• Harden analysis_options.yaml (currently bare flutter_lints, :10). Add under linter.rules: cancel_subscriptions, close_sinks, unawaited_futures, prefer_final_locals, avoid_dynamic_calls. Fix the violations surfaced (the empty-catch/unawaited sites from B7/B10 land here if not in Slice 3).
• Tests (strict TDD, flutter test, mirror test/helpers/fakes.dart patterns). See Test Designs below.

---

Test designs (Slice 6 + seams introduced earlier)

Test	Target	Design
ServicioAlarmas concurrency	servicio_alarmas.dart mutex (Decision 3.5)	Inject mock prefs (setMockInitialValues). Fire N concurrent guardarAlarma/posponerEjecucion/recalcularTodas without awaiting between them; await all; assert the final persisted config reflects ALL writes (no lost update) and the mutation count matches. Without the mutex this fails (read-modify-write race).
Fire dedup across refrescarProgramacion	estado_alarmas.dart _ejecucionesEmitidas + _vigilarAlarmasVencidas (:326-348)	Drive a due alarm; call refrescarProgramacion repeatedly; assert alarmasVencidasStream emits the occurrence exactly once per alarmId:millis key, and the bounded set prunes old keys.
Audio handler rapid source-switch	PluriWaveAudioHandler._colaCambioFuente / _revisionFuente (:280-332)	Issue rapid playMediaItem(A), playMediaItem(B), playMediaItem(C); assert only C's source ends active, earlier revisions are cancelled (revision guard), and no stale error is surfaced from A/B. Use a fake/seam over AudioPlayer URL-set.
Export/import round-trip	new ServicioExportImport (Slice 4a)	Build a full config (favorites, groups, EQ, alarms, vacations); export to JSON; import into a fresh service; assert deep equality. Edge: malformed JSON → graceful empty, not throw.
Recording error recovery	ServicioGrabacionRadio (B10 empty catches :156,165,177,288)	Simulate a recorder failure mid-recording (session-id change / IO error); assert the service transitions to a recoverable error state, releases resources, and a subsequent start succeeds. Covers the Slice 7 reconnect session-id-change interaction.
Snooze logic	AlarmScheduler.snooze/postponeNext anchor + Flutter posponerEjecucionHasta (Decisions 2.1-2.2)	Dart-side: assert posponerAlarma writes snoozeHasta = origin + minutes and that a subsequent recalcularTodas PRESERVES the active snooze (not erased — S4 regression guard). Assert a snoozed native event recorded via the bridge updates state WITHOUT a second programar() call.
Reconnect/backoff	PluriWaveAudioHandler reconnect state machine (Decision 7.2)	Seam over the player so a stall/error can be injected; assert backoff delays follow 1/2/4/8…cap, reconectando state is emitted, success resets the counter, and exhaustion lands on terminal error with the friendly message. Assert an intentional pause during stall cancels reconnect (intent flag).

Kotlin (AlarmScheduler.snooze anchor, FGS type, channels) is NOT covered by flutter test and NOT by flutter analyze; it is verified ON-DEVICE by the user. Design keeps Kotlin diffs small and mirrors existing patterns to minimize compile risk.

---

Cross-cutting decisions and ADRs

Decision	Choice	Rejected alternative	Rationale
Snooze source of truth	Flutter ServicioAlarmas config; native mirrors and reports back via alarmFired/snoozed	Native as source of truth	Flutter already owns recurrence math and persistence; UI reads from it; a second authority is what caused the divergence.
Native→Flutter snooze channel	Reuse existing alarmFired MethodChannel via a static MainActivity.notifyAlarmEvent	New dedicated EventChannel	Fewer moving parts, no new channel lifecycle to manage, engine-dead case covered by cold-start sync.
Channel sound change	New versioned channel id _fire_v2 + one-time delete of old ids	Mutate existing channel	Android locks channel sound at creation; in-place edit is silently ignored.
FGS notification owner	Service startForeground notification (id 92841)	Receiver notification	Service is the long-lived owner; the FSI must persist for the whole ring and be cancelled by stopForeground.
Streaming recovery scope	Jitter tolerance + fast reconnect to live edge	Gap-free time-shift across long outages	Live radio has no rewind history; honesty in acceptance criteria.
Concurrency fix	Single-writer Future-chain mutex + in-memory cache in ServicioAlarmas	Per-mutation lock library	Mirrors the existing _colaCambioFuente pattern; zero new deps; testable.
Slice 4 migration	Backward-compatible getters bridge, 4a/4b split	Big-bang split	Keeps each PR <400 lines and independently revertible.

Risks

• Kotlin compile risk (HIGH): Slices 1, 2, 7-adjacent native edits cannot be compiled here (flutter build forbidden, never run per alarm-clock-module). Mitigation: surgical diffs, mirror existing patterns, schemaVersion bump 2→3 is additive; ask the user to build after Slice 1 before chaining further native work.
• FGS type behavior is OEM/version-sensitive (HIGH): the alarm FGS type + permission pairing must be exact; some OEMs are stricter. Mitigation: pair type and permission precisely; on-device verification by user.
• Channel migration could reset user notification prefs (MEDIUM): deleting old channels and creating _fire_v2 resets per-channel user settings for the ringing channel only. Mitigation: one-time guarded migration; pre-notice channel untouched; document in release notes.
• Snooze sync engine-dead case (MEDIUM): if the Flutter engine is dead when native snoozes, the alarmFired callback is lost; reconciliation relies on the extended cold-start sync (getNativeSnoozeState). Mitigation: import active native snoozes on inicializar.
• Slice 2 and Slice 3 at the 400-line ceiling (MEDIUM): both may need the documented 2a/2b and 3a/3b sub-splits. Flagged for the Review Workload Forecast.
• BackdropFilter cold-GPU stutter on FSI (MEDIUM): the ringing screen blur may drop the first frame on screen-off wake. Mitigation: deferred blur / capped sigma / reduced-motion bypass.
• Reconnect vs alarm wake-up window (MEDIUM): reconnect persistence must never delay the alarm's bundled-WAV fallback. Mitigation: alarm fallback timer takes precedence; reconectando must not be read as playing.
• audio_session interruption vs reconnect fighting (LOW-MEDIUM): a call-pause must set the same intent flag the stall detector reads. Mitigation: shared intent flag (Decision 3.1 ↔ 7.2).

Open assumptions requiring validation

• The alarm-typed FGS started from PluriWaveAlarmReceiver is exempt under the alarm-broadcast FGS-while-in-use allowance on API 34+ — validate on a real API 34/35 device (user build).
• AndroidLoadControl buffer values are tunable but the effective jitter cushion depends on stream bitrate; final values may need on-device tuning.
• MainActivity.notifyAlarmEvent invoked from the service requires the Flutter engine to be alive and the channel bound; the cold-start sync is the fallback — confirm the engine lifecycle assumption holds when the ringing screen is foregrounded.