feat(domain): next-fire resolution, with skip and snooze watermarks
The resolver is pure: it reads an alarm and its ring state and returns what should happen, and the engine does every write. Two rules keep re-resolution honest, and both are load-bearing enough to be worth naming. The grace window lets a fire that arrives a couple of minutes late still count, so a device powered on at 07:01 rings its 07:00 alarm. The handled-occurrence watermark suppresses a candidate only when it is both at-or-before the watermark and at-or-before now — the second conjunct is what stops a user who set the clock forward, let an alarm fire, then set it back from having every future occurrence silenced forever. Skip needs a watermark of its own, because a bare flag eats a second alarm once the skipped occurrence has passed. On a one-shot alarm, skipping the only occurrence is dismissing it, so it disables the alarm instead. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
6e40b72c50
commit
e471c9b750
2 files changed
+505
No files matched your search
@@ -0,0 +1,360 @@
|
||||
package de.jeanlucmakiola.clockula.domain.alarm
|
||||
|
||||
import com.google.common.truth.Truth.assertThat
|
||||
import de.jeanlucmakiola.clockula.domain.Alarm
|
||||
import de.jeanlucmakiola.clockula.domain.RepeatDays
|
||||
import de.jeanlucmakiola.clockula.testing.BERLIN
|
||||
import de.jeanlucmakiola.clockula.testing.alarmAt
|
||||
import de.jeanlucmakiola.clockula.testing.instantAt
|
||||
import de.jeanlucmakiola.clockula.testing.offsetInstant
|
||||
import de.jeanlucmakiola.clockula.testing.ringState
|
||||
import org.junit.jupiter.api.Test
|
||||
import kotlin.time.Duration
|
||||
import kotlin.time.Duration.Companion.hours
|
||||
import kotlin.time.Duration.Companion.minutes
|
||||
import kotlin.time.Duration.Companion.seconds
|
||||
import kotlin.time.Instant
|
||||
|
||||
/**
|
||||
* The function the milestone lives or dies on: pure, total, and called here
|
||||
* with hand-built inputs and no fakes at all.
|
||||
*/
|
||||
class AlarmResolverTest {
|
||||
|
||||
private val morning: Instant = instantAt(BERLIN, "2026-06-10T06:00")
|
||||
|
||||
private fun resolve(
|
||||
alarm: Alarm,
|
||||
state: AlarmRingState = ringState(alarmId = alarm.id),
|
||||
now: Instant = morning,
|
||||
fireGrace: Duration = AlarmRing.FIRE_GRACE,
|
||||
): AlarmResolution =
|
||||
AlarmResolver.resolve(alarm, state, now, BERLIN, AlarmRing.AUTO_SILENCE_AFTER, fireGrace)
|
||||
|
||||
// --- T32–T34: the disabled and plain cases ---
|
||||
|
||||
@Test
|
||||
fun `a disabled alarm clears its volatile state but keeps the dismissal watermark`() {
|
||||
val alarm = alarmAt(hour = 7, enabled = false, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val handled = offsetInstant("2026-06-10T05:00+02:00")
|
||||
val state = ringState(
|
||||
snoozedUntil = morning + 5.minutes,
|
||||
snoozeCount = 2,
|
||||
ringingSince = morning - 1.minutes,
|
||||
handledOccurrence = handled,
|
||||
skippedOccurrence = morning + 1.hours,
|
||||
)
|
||||
|
||||
val resolution = resolve(alarm, state)
|
||||
|
||||
assertThat(resolution).isEqualTo(
|
||||
AlarmResolution(
|
||||
alarmId = alarm.id,
|
||||
nextFire = null,
|
||||
source = FireSource.NONE,
|
||||
state = ringState(handledOccurrence = handled),
|
||||
),
|
||||
)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `an enabled one-shot alarm resolves to its next daily occurrence`() {
|
||||
val alarm = alarmAt(hour = 7)
|
||||
|
||||
val resolution = resolve(alarm)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-10T07:00+02:00"))
|
||||
assertThat(resolution.source).isEqualTo(FireSource.OCCURRENCE)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a weekday alarm resolved on a Saturday lands on Monday`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.WEEKDAYS)
|
||||
|
||||
val resolution = resolve(alarm, now = instantAt(BERLIN, "2026-06-13T12:00"))
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-15T07:00+02:00"))
|
||||
}
|
||||
|
||||
// --- T35–T38: snooze ---
|
||||
|
||||
@Test
|
||||
fun `a pending snooze is what fires next`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val snooze = morning + 5.minutes
|
||||
|
||||
val resolution = resolve(alarm, ringState(snoozedUntil = snooze, snoozeCount = 1))
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(snooze)
|
||||
assertThat(resolution.source).isEqualTo(FireSource.SNOOZE)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a snooze that came due while the device was off is still honoured at its own instant`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val snooze = morning - 1.minutes
|
||||
|
||||
val resolution = resolve(alarm, ringState(snoozedUntil = snooze, snoozeCount = 1))
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(snooze)
|
||||
assertThat(resolution.source).isEqualTo(FireSource.SNOOZE)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a snooze older than the auto-silence window is abandoned`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
|
||||
val resolution = resolve(alarm, ringState(snoozedUntil = morning - 11.minutes, snoozeCount = 2))
|
||||
|
||||
assertThat(resolution.state.snoozedUntil).isNull()
|
||||
assertThat(resolution.state.snoozeCount).isEqualTo(0)
|
||||
assertThat(resolution.source).isEqualTo(FireSource.OCCURRENCE)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `an occurrence earlier than the snooze wins while the snooze stays in state`() {
|
||||
val alarm = alarmAt(hour = 23, minute = 45, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val now = instantAt(BERLIN, "2026-06-10T23:40")
|
||||
val snooze = instantAt(BERLIN, "2026-06-10T23:50")
|
||||
|
||||
val resolution = resolve(alarm, ringState(snoozedUntil = snooze, snoozeCount = 1), now = now)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-10T23:45+02:00"))
|
||||
assertThat(resolution.source).isEqualTo(FireSource.OCCURRENCE)
|
||||
assertThat(resolution.state.snoozedUntil).isEqualTo(snooze)
|
||||
}
|
||||
|
||||
// --- T39–T42: ringing ---
|
||||
|
||||
@Test
|
||||
fun `an alarm ringing inside the window is resumed rather than scheduled`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val state = ringState(ringingSince = morning - 3.minutes, handledOccurrence = morning - 3.minutes)
|
||||
|
||||
val resolution = resolve(alarm, state)
|
||||
|
||||
assertThat(resolution.source).isEqualTo(FireSource.RESUMED_RING)
|
||||
assertThat(resolution.nextFire).isNull()
|
||||
assertThat(resolution.state).isEqualTo(state)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `an alarm ringing past the window is auto-dismissed and re-scheduled`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val state = ringState(
|
||||
ringingSince = morning - 11.minutes,
|
||||
snoozeCount = 1,
|
||||
handledOccurrence = morning - 11.minutes,
|
||||
)
|
||||
|
||||
val resolution = resolve(alarm, state)
|
||||
|
||||
assertThat(resolution.state.ringingSince).isNull()
|
||||
assertThat(resolution.state.snoozeCount).isEqualTo(0)
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-10T07:00+02:00"))
|
||||
assertThat(resolution.source).isEqualTo(FireSource.OCCURRENCE)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a ring exactly as old as the auto-silence window has timed out`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val state = ringState(ringingSince = morning - AlarmRing.AUTO_SILENCE_AFTER)
|
||||
|
||||
val resolution = resolve(alarm, state)
|
||||
|
||||
assertThat(resolution.source).isEqualTo(FireSource.OCCURRENCE)
|
||||
assertThat(resolution.state.ringingSince).isNull()
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a clock moved backwards under a ringing alarm keeps it ringing`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val state = ringState(ringingSince = morning + 30.minutes)
|
||||
|
||||
val resolution = resolve(alarm, state)
|
||||
|
||||
assertThat(resolution.source).isEqualTo(FireSource.RESUMED_RING)
|
||||
}
|
||||
|
||||
// --- T43–T44, T58: the handled-occurrence watermark ---
|
||||
|
||||
@Test
|
||||
fun `an occurrence already handled is suppressed while it is still in the past`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val occurrence = offsetInstant("2026-06-10T07:00+02:00")
|
||||
val now = occurrence + 30.seconds
|
||||
|
||||
val resolution = resolve(alarm, ringState(handledOccurrence = occurrence), now = now)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-11T07:00+02:00"))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a watermark in the future suppresses nothing, so a backwards clock cannot silence the future`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val occurrence = offsetInstant("2026-06-10T07:00+02:00")
|
||||
|
||||
val resolution = resolve(alarm, ringState(handledOccurrence = occurrence), now = morning)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(occurrence)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `suppression scans past every handled candidate rather than giving up`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val now = instantAt(BERLIN, "2026-06-10T08:00")
|
||||
val handled = offsetInstant("2026-06-10T07:00+02:00")
|
||||
|
||||
val resolution = resolve(alarm, ringState(handledOccurrence = handled), now = now, fireGrace = 72.hours)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-11T07:00+02:00"))
|
||||
}
|
||||
|
||||
// --- T45–T51, T55: skip ---
|
||||
|
||||
@Test
|
||||
fun `an unarmed skip arms itself on the first candidate and fires the second`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY, skipNextOccurrence = true)
|
||||
|
||||
val resolution = resolve(alarm)
|
||||
|
||||
assertThat(resolution.state.skippedOccurrence).isEqualTo(offsetInstant("2026-06-10T07:00+02:00"))
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-11T07:00+02:00"))
|
||||
assertThat(resolution.clearSkipFlag).isFalse()
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `arming a skip is idempotent`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY, skipNextOccurrence = true)
|
||||
val armed = resolve(alarm)
|
||||
|
||||
val again = resolve(alarm, armed.state)
|
||||
|
||||
assertThat(again).isEqualTo(armed)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a skip watermark in the future holds, and nothing is rewritten`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY, skipNextOccurrence = true)
|
||||
val watermark = offsetInstant("2026-06-10T07:00+02:00")
|
||||
|
||||
val resolution = resolve(alarm, ringState(skippedOccurrence = watermark))
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-11T07:00+02:00"))
|
||||
assertThat(resolution.state.skippedOccurrence).isEqualTo(watermark)
|
||||
assertThat(resolution.clearSkipFlag).isFalse()
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a skip watermark that has passed is consumed without letting its occurrence ring`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY, skipNextOccurrence = true)
|
||||
val watermark = offsetInstant("2026-06-10T07:00+02:00")
|
||||
|
||||
val resolution = resolve(alarm, ringState(skippedOccurrence = watermark), now = watermark + 30.seconds)
|
||||
|
||||
assertThat(resolution.clearSkipFlag).isTrue()
|
||||
assertThat(resolution.state.skippedOccurrence).isNull()
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-11T07:00+02:00"))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `skipping a one-shot alarm disables it`() {
|
||||
val alarm = alarmAt(hour = 7, skipNextOccurrence = true)
|
||||
|
||||
val resolution = resolve(alarm)
|
||||
|
||||
assertThat(resolution.nextFire).isNull()
|
||||
assertThat(resolution.disableAlarm).isTrue()
|
||||
assertThat(resolution.clearSkipFlag).isTrue()
|
||||
assertThat(resolution.state.skippedOccurrence).isNull()
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a stale watermark with the flag off is cleared`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY, skipNextOccurrence = false)
|
||||
|
||||
val resolution = resolve(alarm, ringState(skippedOccurrence = offsetInstant("2026-06-09T07:00+02:00")))
|
||||
|
||||
assertThat(resolution.state.skippedOccurrence).isNull()
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-10T07:00+02:00"))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `arming a skip is deferred while a snooze is still pending`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY, skipNextOccurrence = true)
|
||||
val snooze = morning + 5.minutes
|
||||
|
||||
val resolution = resolve(alarm, ringState(snoozedUntil = snooze, snoozeCount = 1))
|
||||
|
||||
assertThat(resolution.source).isEqualTo(FireSource.SNOOZE)
|
||||
assertThat(resolution.nextFire).isEqualTo(snooze)
|
||||
assertThat(resolution.state.skippedOccurrence).isNull()
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `a skip over a spring-forward night arms on the shifted occurrence`() {
|
||||
val alarm = alarmAt(hour = 2, minute = 30, repeatDays = RepeatDays.EVERY_DAY, skipNextOccurrence = true)
|
||||
|
||||
val resolution = resolve(alarm, now = instantAt(BERLIN, "2026-03-28T12:00"))
|
||||
|
||||
assertThat(resolution.state.skippedOccurrence).isEqualTo(offsetInstant("2026-03-29T03:30+02:00"))
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-03-30T02:30+02:00"))
|
||||
}
|
||||
|
||||
// --- T52–T54: the fire-grace window ---
|
||||
|
||||
@Test
|
||||
fun `an occurrence a minute in the past is still inside the grace window`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val occurrence = offsetInstant("2026-06-10T07:00+02:00")
|
||||
|
||||
val resolution = resolve(alarm, now = occurrence + 60.seconds)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(occurrence)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `an occurrence beyond the grace window is missed, not rung late`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val occurrence = offsetInstant("2026-06-10T07:00+02:00")
|
||||
|
||||
val resolution = resolve(alarm, now = occurrence + 3.minutes)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(offsetInstant("2026-06-11T07:00+02:00"))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `an occurrence exactly at now still counts`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val occurrence = offsetInstant("2026-06-10T07:00+02:00")
|
||||
|
||||
val resolution = resolve(alarm, now = occurrence)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(occurrence)
|
||||
}
|
||||
|
||||
// --- T56–T57: absolute instants, and purity ---
|
||||
|
||||
@Test
|
||||
fun `a snooze is an absolute instant that a DST transition cannot move`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.EVERY_DAY)
|
||||
val snooze = offsetInstant("2026-03-29T03:45+02:00")
|
||||
|
||||
val resolution = resolve(alarm, ringState(snoozedUntil = snooze, snoozeCount = 1), now = snooze - 5.minutes)
|
||||
|
||||
assertThat(resolution.nextFire).isEqualTo(snooze)
|
||||
assertThat(resolution.source).isEqualTo(FireSource.SNOOZE)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `resolving twice gives the same answer and leaves the input state untouched`() {
|
||||
val alarm = alarmAt(hour = 7, repeatDays = RepeatDays.WEEKDAYS, skipNextOccurrence = true)
|
||||
val state = ringState(snoozeCount = 1, handledOccurrence = morning - 1.hours)
|
||||
val copy = state.copy()
|
||||
|
||||
val first = resolve(alarm, state)
|
||||
|
||||
assertThat(resolve(alarm, state)).isEqualTo(first)
|
||||
assertThat(state).isEqualTo(copy)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user