pluriwave/openspec/changes/alarm-system-overhaul/design.md

Design: Alarm System Overhaul — Fail-Safe Stop/Dismiss

Technical Approach

Evolve the existing native-owns-audio architecture; no rewrite. The single key enabler is that the service, activity and receivers share ONE process (confirmed: no android:process), so MainActivity can read a @Volatile companion field on PluriWaveAlarmService synchronously to build verifiable stop results without a service round-trip. Four surgical additions: (1) an id-agnostic fail-safe stop that can never no-op a live ring; (2) an atomic stopEverything() all stop paths funnel through; (3) an AlarmManager-armed FIRED→MISSED auto-silence bound; (4) a durable firing record in the existing device-protected prefs for process-death recovery. All decision logic lives in Dart (mutation-while-ringing guard, stop-result handling) behind new fake switches; Kotlin stays trivially static-grep-verifiable. Maps to proposal P0 (stop-safety) + P1 (fallbacks); P2 deferred.

Architecture Decisions

Decision 1 — Native stop semantics (verify-and-report)

Option	Tradeoff	Decision
Service writes result to static field, channel polls	Race between async onStartCommand and channel read	Rejected
Channel reads @Volatile companion snapshot (same process), then dispatches id-agnostic stop	Snapshot is authoritative pre-stop; stop cannot no-op	Chosen

PluriWaveAlarmService gains companion @Volatile var activeRingingId: String? (set in startAlarm, cleared in stopEverything). New channel methods:

• getActiveRingingAlarmId(): String? — synchronous companion read; this is HOW Dart knows what is ringing.
• stopActiveAlarm(): { stopped: bool, wasRinging: bool, activeAlarmId: String? } — reads the snapshot, dispatches ACTION_STOP_ACTIVE (id-agnostic full teardown), returns the pre-stop snapshot. stopped = a non-no-op teardown was dispatched (always true on success path); wasRinging = activeAlarmId != null. Error contract: internal exception → result.error("STOP_FAILED", msg, null); Dart treats a thrown channel error OR stopped==false as failure → retryable force-stop.

Concurrent case: only one alarm rings at a time (startAlarm early-returns while activeAlarmId != null). stopActiveAlarm silences the ONE audible ring and returns its id so Dart reconciles; the id-agnostic form is used ONLY by the ringing UI Stop and the notification Stop action (explicit "silence what I hear" intents). Mutation guards (Decision 5) gate on the returned activeAlarmId so a background toggle of a non-ringing alarm never stops a live one. Ambiguity fails toward silence per the acceptance bar.

Decision 2 — Atomic stopEverything()

Extract the current teardown block (PluriWaveAlarmService.kt L410-433) into one private stopEverything(): cancel fallback+fade runnables, player.stop()/release(), activeAlarmId=null, clear companion, releaseWakeLock(), abandonAlarmAudioFocus(), cancel notification, AlarmScheduler(this).clearFiringRecord(id) + cancelAutoSilence(id), stopForeground(REMOVE), stopSelf(). Every path routes through it: ACTION_STOP (id match/null), ACTION_STOP_ACTIVE, ACTION_SNOOZE, ACTION_MISSED, onDestroy. stopAlarm(id) stays as the id-scoped wrapper (foreign-id mismatch → cancel that id's notification only, then return; else stopEverything()).

Decision 3 — Auto-silence (AlarmManager-armed MISSED)

Option	Tradeoff	Decision
In-service Handler.postDelayed(10min)	Dies with process; no missed-notification/rearm if service later gone	Rejected
AlarmManager setExactAndAllowWhileIdle → receiver ACTION_MISSED	Survives process death; posts missed notification + rearm even if FGS was killed; reuses existing scheduling infra	Chosen

Fixed 10 min (matches the existing wakelock cap; configurability = P2). Armed in onAlarmFired (already runs at fire time and already rearms the next occurrence, so onAlarmMissed must NOT re-rearm — only silence + notify + clear record). Cancelled in snooze, skipNext, cancelAlarm and stopEverything. onAlarmMissed(id): stop the service if this id still rings, post a missed notification (reuse the pre-notice non-FSI channel + AlarmNotificationStrings, new keys missedTitle/missedText), clear the firing record.

Decision 4 — Durable firing record

Store in the existing device-protected prefs pluriwave_alarm_scheduler (AlarmScheduler.prefs(), direct-boot safe). Schema: KEY_FIRING_IDS (string set) + firing_<id> → firedAtMillis (Long). Write in onAlarmFired BEFORE the service/audio starts (receiver runs onAlarmFired first). Clear in stopEverything/onAlarmMissed. onStartCommand re-validation: startAlarm checks firingRecordAgeMillis(id); if > AUTO_SILENCE_MILLIS → abort start, run onAlarmMissed cleanup (defends against redelivery/resurrection; START_NOT_STICKY already prevents blind restart). Boot cleanup: reschedulePersistedAlarms calls cleanupStaleFiringRecords() first — any record older than the window is cleared as missed, so a reboot mid-ring never resurrects audio.

Decision 5 — Dart orchestration

PuertoAlarmasAndroid gains Future<String?> alarmaSonandoId() and Future<ResultadoDetencion> detenerSonidoActivo() (new value type ResultadoDetencion{ bool detenido; bool estabaSonando; String? alarmaId; }); detenerSonidoNativo stays for compatibility. EstadoAlarmas gains a shared guard _detenerSiEstaSonando(String id): query alarmaSonandoId(); if it equals id → detenerSonidoActivo(). Wired into guardarAlarma/cambiarActiva(false)/eliminarAlarma (upgrade its existing detenerSonidoNativo call) so any mutation of the ringing alarm silences it first. finalizarEjecucion (the Stop path) calls detenerSonidoActivo() directly; on failure it sets _error (same channel the snooze SnackBar already reads). New forzarDetencion() re-invokes detenerSonidoActivo() for the retry action.

UX (pantalla_alarma_sonando.dart): keep dismiss-by-design, EXCEPT on a verified _detener() failure — a timed SnackBar would auto-dismiss while the alarm is still audibly ringing, hiding the only retry affordance. Amended by review round 2: instead the screen stays up and renders a persistent in-screen banner (alarmStopFailedMessage + a alarmForceStopAction button calling forzarDetencion()) that clears only on a confirmed stop, never on a timer.

l10n (new keys): alarmStopFailedMessage, alarmForceStopAction, alarmMissedNotificationTitle, alarmMissedNotificationText({name}). Provide en (template, with @-metadata + placeholders) and es. Policy for the other 12 locales: given the ARB placeholder-corruption CI guard, define placeholder metadata ONLY in the template and mirror it byte-exactly in es; omit the keys from the remaining locales so gen-l10n falls back to en at runtime (untranslated-message warning is acceptable) — this avoids introducing placeholder metadata into 12 files and the corruption risk the guard protects against. Flag full translation as a follow-up.

Decision 6 — P1 permission/FSI fallbacks

FSI fallback is largely automatic: buildNotification keeps IMPORTANCE_HIGH + setFullScreenIntent, which the platform degrades to heads-up when canUseFullScreenIntent() is false. The P1 work is the in-app WARNING: diagnostics already exposes canUseFullScreenIntent/notificationsEnabled/canScheduleExactAlarms; surface warning banners on the existing diagnostics/settings surface bound to EstadoAlarmas.diagnostico (new warning strings). Lightly specified; sliced after P0.

Data Flow

Fire:  Receiver(ACTION_FIRE) ─→ AlarmScheduler.onAlarmFired
          │  writes firing record (before audio) + arms MISSED + rearms next
          └─→ Service.startAlarm ─→ companion.activeRingingId=id ─→ audio

Stop:  RingingUI/NotifStop ─→ (channel) stopActiveAlarm
          │  reads companion snapshot ─→ result{stopped,wasRinging,activeAlarmId}
          └─→ ACTION_STOP_ACTIVE ─→ stopEverything() ─→ clear record + cancel MISSED

Mutate: EstadoAlarmas.guardar/cambiar/eliminar ─→ alarmaSonandoId()
          └─ if == target ─→ detenerSonidoActivo() ─→ stopEverything()

Timeout: AlarmManager(MISSED) ─→ Receiver(ACTION_MISSED) ─→ onAlarmMissed
          └─→ stop service + missed notification + clear record   (no re-rearm)

File Changes

File	Action	Change
PluriWaveAlarmService.kt	Modify	companion activeRingingId/ACTION_STOP_ACTIVE/AUTO_SILENCE_MILLIS/stopActive(); onStartCommand +ACTION_STOP_ACTIVE; startAlarm sets companion + stale-record re-validation; extract stopEverything()
AlarmScheduler.kt	Modify	recordFiring/clearFiringRecord/firingRecordAgeMillis/cleanupStaleFiringRecords; armAutoSilence/cancelAutoSilence/onAlarmMissed; onAlarmFired+arm+record; reschedulePersistedAlarms+cleanup; cancel in snooze/skipNext/cancelAlarm
PluriWaveAlarmReceiver.kt	Modify	ACTION_MISSED constant + branch → onAlarmMissed; pendingMissedIntent helper
MainActivity.kt	Modify	channel stopActiveAlarm (returns map) + getActiveRingingAlarmId; pass missed strings in setNotificationStrings
AlarmNotificationStrings.kt	Modify	missedTitle/missedText getters+setters
servicio_alarmas_android.dart	Modify	ResultadoDetencion; alarmaSonandoId(); detenerSonidoActivo(); interface additions
estado/estado_alarmas.dart	Modify	_detenerSiEstaSonando guard; wire into guardar/cambiar/eliminar/finalizar; forzarDetencion(); missed-event handling
pantallas/pantalla_alarma_sonando.dart	Modify	force-stop SnackBar action on stop failure
l10n/arb/app_en.arb, app_es.arb	Modify	4 new keys (en template + es)
test/helpers/fakes_alarmas.dart	Modify	fallaDetener, alarmaSonandoIdValor, detencionesActivas, new interface impls
test/** (Dart)	New	stop/mutation/force-stop/missed tests

Interfaces / Contracts

class ResultadoDetencion {
  final bool detenido;       // stop dispatched, cannot no-op
  final bool estabaSonando;  // audio was live
  final String? alarmaId;    // what was actually ringing
}
abstract class PuertoAlarmasAndroid {
  Future<String?> alarmaSonandoId();            // getActiveRingingAlarmId
  Future<ResultadoDetencion> detenerSonidoActivo(); // stopActiveAlarm
  // ...existing members unchanged
}

Channel (pluriwave/alarm_scheduler): getActiveRingingAlarmId → String?, stopActiveAlarm → {stopped,wasRinging,activeAlarmId}.

Testing Strategy

Layer	What	How
Unit (Dart)	Stop success/failure surfaces result	fallaDetener → EstadoAlarmas.error set; assert detenerSonidoActivo called
Unit (Dart)	Mutation-while-ringing stops audio	alarmaSonandoIdValor=target → cambiarActiva(false)/guardarAlarma(inactive)/eliminarAlarma assert force-stop invoked
Unit (Dart)	No false stop on non-ringing target	mismatched alarmaSonandoIdValor → assert force-stop NOT invoked
Widget	Force-stop retry affordance	stop failure → SnackBar with action → action calls forzarDetencion
Unit (Dart)	Missed event bookkeeping	native missed event → completarEjecucion recorded
On-device QA	Native-only proofs	see checklist

On-device QA checklist (only a device proves): Stop from ringing UI (id match AND mismatch); Stop from lock-screen notification; disable/edit/delete while ringing; 10-min untouched → auto-silence + missed notification + repeating rearm; kill app mid-ring (audio stops); reboot mid-ring (boot cleanup, no resurrection); concurrent second alarm; FSI-denied heads-up fallback.

Threat Matrix

N/A — no routing, shell, subprocess, VCS/PR automation, executable-file classification, or shell/process-integration boundary. (Android service/IPC is not in scope of the shell/subprocess threat matrix.)

Migration / Rollout

No migration. New pref keys (firing_<id>, KEY_FIRING_IDS) are additive and self-cleaning by age; orphaned entries are ignored if the reader is reverted. Single feature branch to main; P0 first, P1 as a follow-up slice within budget.

Consequences / Rollback

Ships to live alarm users. Regression manifestations & mitigations:

• Wrong concurrent alarm silenced — bounded by the one-ring-at-a-time guard; stopActiveAlarm returns the stopped id for reconciliation.
• Auto-silence fires early — bounded to 10 min = wakelock cap; user re-arm unaffected.
• Firing-record bug → false "missed" or blocked start — age-gated; stale-only cleanup; worst case a legitimate ring is cut at the 10-min bound (still better than the unbounded incident).

Fastest rollback: git revert the merge/PR — native and Dart changes are additive to existing stop paths, so revert restores current behavior; orphaned firing-record keys go unread (no migration rollback needed).

Open Questions

• Missed notification channel: reuse the pre-notice channel vs. a dedicated low-importance missed channel? (Leaning reuse for minimal diff; confirm in tasks.)
• Should finalizarEjecucion return Future<bool> for a cleaner contract, or keep the _error-field convention the snooze path uses? (Leaning _error for consistency.)