fix(alarm): fail-safe alarm system overhaul (SDD alarm-system-overhaul, slice A)
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.
This commit is contained in:
Javier Bautista Fernández
@@ -0,0 +1,93 @@
|
||||
# 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
|
||||
@@ -0,0 +1,125 @@
|
||||
# Delta for Native Alarms
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Fail-Safe stopActive Semantics
|
||||
|
||||
`PluriWaveAlarmService` MUST expose an id-agnostic stop action (`stopActive`), used by the ringing UI and the notification Stop action, that stops the currently-active ring regardless of the alarm id it is called with. It MUST NEVER silently no-op while a ring is active. On concurrent-alarm ambiguity, it MUST verify state and report the outcome, failing toward silencing the active ring.
|
||||
|
||||
#### Scenario: Stop with mismatched id still silences the active ring
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN `activeAlarmId = A` is ringing
|
||||
- WHEN `stopActive` is invoked with id B (mismatch)
|
||||
- THEN ring A is stopped, not silently ignored, and the caller gets a verified result
|
||||
|
||||
#### Scenario: Stop with no active ring reports cleanly
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN no alarm is currently ringing
|
||||
- WHEN `stopActive` is invoked
|
||||
- THEN it reports "nothing to stop" rather than throwing or hanging
|
||||
|
||||
#### Scenario: Concurrent ambiguity fails toward silence
|
||||
**Testability**: [device-qa]
|
||||
|
||||
- GIVEN two alarms could plausibly be "the active one"
|
||||
- WHEN `stopActive` resolves the ambiguity
|
||||
- THEN the active ring MUST be silenced (over-stop preferred over leaving it ringing)
|
||||
|
||||
### Requirement: Atomic Stop Coupling
|
||||
|
||||
Every stop path MUST perform `stopForeground(STOP_FOREGROUND_REMOVE)`, `stopSelf()`, and wakelock release together, with no branch that performs a subset.
|
||||
|
||||
#### Scenario: Stop path releases all three resources together
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN any stop entry point in `PluriWaveAlarmService`
|
||||
- WHEN read/inspected
|
||||
- THEN all three teardown calls are reachable from it with no partial-teardown branch
|
||||
|
||||
### Requirement: Bounded Auto-Silence at 10 Minutes
|
||||
|
||||
If a fired alarm is not stopped within 10 minutes, the system MUST transition it FIRED→MISSED via the atomic stop path, post a missed-alarm notification, rearm the next occurrence for repeating alarms, and leave one-shot alarms disabled.
|
||||
|
||||
#### Scenario: Unattended ring auto-silences at 10 minutes
|
||||
**Testability**: [kotlin-static] + [device-qa]
|
||||
|
||||
- GIVEN an alarm fires and is never stopped
|
||||
- WHEN 10 minutes elapse
|
||||
- THEN audio stops via the atomic stop path and a missed notification posts
|
||||
|
||||
#### Scenario: Repeating alarm rearms after auto-silence
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN a repeating alarm auto-silences
|
||||
- WHEN the MISSED transition completes
|
||||
- THEN `AlarmScheduler` arms the next occurrence
|
||||
|
||||
#### Scenario: One-shot alarm disables after auto-silence
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN a one-shot alarm auto-silences
|
||||
- WHEN the MISSED transition completes
|
||||
- THEN the alarm is left disabled, not rearmed
|
||||
|
||||
### Requirement: Durable Firing Record + Restart Re-Validation
|
||||
|
||||
Before playback starts, the service MUST persist a durable "firing since T" record. `onStartCommand` MUST re-validate it on every entry, and the service MUST run `START_NOT_STICKY`. The record MUST clear only on a confirmed stop or a completed auto-silence transition.
|
||||
|
||||
#### Scenario: Firing record persists before audio starts
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN a fire event
|
||||
- WHEN `startAlarm` begins
|
||||
- THEN a durable record is written before `MediaPlayer.start()`
|
||||
|
||||
#### Scenario: onStartCommand re-validates on restart
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN the service process is killed and restarted by the OS
|
||||
- WHEN `onStartCommand` runs again
|
||||
- THEN it checks the record's age/state before resuming any audio action and returns `START_NOT_STICKY`
|
||||
|
||||
#### Scenario: Confirmed stop clears the record
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN a confirmed stop via `stopActive`
|
||||
- WHEN the atomic stop path completes
|
||||
- THEN the durable firing record is cleared
|
||||
|
||||
### Requirement: Boot/Restart Cleanup of Stale Firing Records
|
||||
|
||||
On boot/unlock/package-replace, a durable firing record older than the 10-minute auto-silence bound MUST be treated as missed and cleaned up, not left dangling.
|
||||
|
||||
#### Scenario: Stale record cleaned at boot
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN a firing record older than 10 minutes exists at boot
|
||||
- WHEN `PluriWaveBootReceiver` runs `reschedulePersistedAlarms`
|
||||
- THEN the stale record is cleared and treated as a MISSED transition
|
||||
|
||||
### Requirement: P1 — FSI, Exact-Alarm, and Notification-Permission Fallbacks
|
||||
|
||||
The system MUST call `canUseFullScreenIntent()` before relying on FSI and fall back to a heads-up notification when denied. It MUST show an in-app warning when exact-alarm scheduling permission is denied and when `POST_NOTIFICATIONS` is denied.
|
||||
|
||||
#### Scenario: FSI unavailable falls back to heads-up
|
||||
**Testability**: [kotlin-static]
|
||||
|
||||
- GIVEN `canUseFullScreenIntent()` returns false
|
||||
- WHEN a fire notification is built
|
||||
- THEN it posts as heads-up instead of FSI
|
||||
|
||||
#### Scenario: Exact-alarm denial warns in-app
|
||||
**Testability**: [dart-testable]
|
||||
|
||||
- GIVEN exact-alarm scheduling permission is denied
|
||||
- WHEN the user schedules/saves an alarm
|
||||
- THEN an in-app warning is shown
|
||||
|
||||
#### Scenario: POST_NOTIFICATIONS denial warns in-app
|
||||
**Testability**: [dart-testable]
|
||||
|
||||
- GIVEN `POST_NOTIFICATIONS` permission is denied
|
||||
- WHEN the user schedules an alarm
|
||||
- THEN an in-app warning is shown
|
||||
Reference in New Issue
Block a user