Javier Bautista Fernández
29f7d54e85
Root-cause fix for the unstoppable-alarm incident (alarm rang 15 minutes, only uninstall silenced it) plus systematic hardening of every stop path. Native (Kotlin): - Verified stop: stopActiveAlarm now derives its result from the real post-teardown state (companion instance + synchronous stopEverything + activeRingingId check) instead of reporting unconditional success. - Atomic teardown: every stop path (stop action, notification button, snooze, missed, onDestroy, startForeground failure) funnels through one stopEverything() covering audio, wakelock, notification, foreground state and firing-record cleanup; player.release() guarded. - Bounded ringing: 10-minute auto-silence armed via AlarmManager fires a FIRED->MISSED transition with a localized missed-alarm notification; repeating alarms keep their native rearm, deleted alarms never produce ghost MISSED notifications. - Durable firing record with onStartCommand re-validation (resurrection guard) and boot-time stale cleanup; firing records cleared on every refuse/mismatch/cancel path. - New notification-only dismissal channel (dismissAlarmNotificationOnly) so UI-level dedup can never kill a live ring's audio. Flutter (Dart): - Stop/disable/edit/delete of a ringing alarm always attempt to silence it; on native-query failure the stop falls back toward silence via the id-scoped legacy stop. - Verified-stop results surface failures: the ringing screen keeps dismiss-by-design on success, but on a verified failure it stays up with a persistent force-stop banner (guarded against double-dismiss) and auto-dismisses if the ring ends externally (missed/notification). - Missed events sync alarm bookkeeping without opening the ringing UI. - 4 new l10n keys translated across all 13 locales (ARB guard green). 550 tests green, analyzer clean. Reviewed in 3 adversarial 4-lens rounds (2 deterministic + 1 refuter-corroborated critical fixed); formal gentle-ai receipt waived by maintainer authorization (correction scope legitimately exceeded the frozen genesis paths). On-device QA checklist in openspec/changes/alarm-system-overhaul/tasks.md pending before archive.
94 lines
4.0 KiB
Markdown
94 lines
4.0 KiB
Markdown
# Alarm Stop Safety Specification
|
|
|
|
## Purpose
|
|
|
|
Dart-side fail-safe orchestration: every surface that can act on a ringing alarm (ringing-screen Stop/Snooze, alarm-list disable/toggle, edit/save, delete) MUST deterministically silence a live ring or surface a visible, retryable failure. Dismiss-by-design (the ringing screen always closes) is preserved but MUST NOT mask a failed native stop.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Mutation-While-Ringing Stop Guard
|
|
|
|
`EstadoAlarmas` MUST route any mutation targeting the currently-ringing alarm — disable/toggle (`cambiarActiva`), edit/save (`guardarAlarma`), delete (`eliminarAlarma`) — through one centralized stop-first guard, not per-call-site logic.
|
|
|
|
#### Scenario: Toggling the ringing alarm off stops audio
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN alarm X is ringing and active
|
|
- WHEN `cambiarActiva(X, false)` is called
|
|
- THEN `detenerSonidoNativo(X)` runs before/alongside `programar`/`cancelar`
|
|
|
|
#### Scenario: Editing/saving the ringing alarm stops audio
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN alarm X is ringing
|
|
- WHEN `guardarAlarma` is called with an edited config for id X
|
|
- THEN the stop guard fires before the save persists
|
|
|
|
#### Scenario: Deleting the ringing alarm stops audio (regression lock)
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN alarm X is ringing
|
|
- WHEN `eliminarAlarma(X)` is called
|
|
- THEN `detenerSonidoNativo(X)` runs before `cancelar` (locks in existing correct behavior)
|
|
|
|
#### Scenario: Mutating a non-ringing alarm does not trigger the guard
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN alarm Y is ringing, alarm Z is not
|
|
- WHEN `cambiarActiva(Z, ...)` or `guardarAlarma(Z)` is called
|
|
- THEN no stop call targets Y
|
|
|
|
### Requirement: Stop/Snooze Result Verification
|
|
|
|
Stop (`detenerSonidoNativo`) and snooze channel calls MUST return a success/failure/unconfirmed result instead of only throwing or being swallowed. `EstadoAlarmas` MUST record this outcome per alarm.
|
|
|
|
#### Scenario: Native stop confirms success
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN the stop channel call resolves with `confirmed=true`
|
|
- WHEN `_detener()` completes
|
|
- THEN `EstadoAlarmas` records a confirmed-stop state for that alarm
|
|
|
|
#### Scenario: Native stop reports unconfirmed/failure
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN the fake channel is set to fail or return `confirmed=false`
|
|
- WHEN `_detener()`/`_posponer()` runs
|
|
- THEN `EstadoAlarmas` records a failed/unconfirmed state, never a confirmed one
|
|
|
|
### Requirement: Retryable Force-Stop Affordance
|
|
|
|
When a stop/snooze attempt is not confirmed, the app MUST present a persistent, retryable "Force stop" affordance until a confirmed stop is recorded or the alarm is externally cleared. Dismiss-by-design (screen closing) stays independent of this affordance.
|
|
|
|
#### Scenario: Failed stop surfaces Force stop
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN `_detener()` receives an unconfirmed/failure result
|
|
- WHEN the ringing screen finishes its dismiss-by-design close
|
|
- THEN a persistent retryable Force-stop affordance appears
|
|
|
|
#### Scenario: Retrying force-stop attempts stop again
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN a Force-stop affordance is visible after a failed attempt
|
|
- WHEN the user retries
|
|
- THEN `detenerSonidoNativo` is invoked again; success clears the affordance, failure keeps it visible
|
|
|
|
#### Scenario: Confirmed stop shows no failure UI
|
|
**Testability**: [dart-testable]
|
|
|
|
- GIVEN a confirmed-stop result
|
|
- WHEN the screen dismisses
|
|
- THEN no Force-stop affordance appears
|
|
|
|
### Requirement: Notification Stop/Snooze Stays Native-Only
|
|
|
|
Notification Stop/Snooze actions use `PendingIntent.getService` directly (native-only, Flutter-independent) and remain outside this Dart guard's scope; only Dart-initiated mutations and in-app screens are covered here.
|
|
|
|
#### Scenario: Notification action bypasses the Dart guard by design
|
|
**Testability**: [kotlin-static]
|
|
|
|
- GIVEN a fire notification with Stop/Snooze actions
|
|
- WHEN the user taps either action
|
|
- THEN it invokes the native service directly, never touching `EstadoAlarmas`' guard
|