wake-alarm/DOCS-sick-days.md

Sick days — the phone picker, the silent ring, the pre-alarm sync

The pool itself is ~/src/utils/sickdays (Python): every day is normal until it is marked sick, today or later only, no cap, no reason, never also a free day. Read its README for the rules and the RTDB wire format. This file covers the phone half.

On a sick day the phone does not ring, the stick does not judge the day, and nothing ring-related is recorded. It is not a free day: separate pool, separate RTDB node (sickdays-sync/devices), separate native cache, separate screen, and every log line and event says sick_day.

Where things are

Picker	phone_app/lib/screens/sick_days_screen.dart (+ sick_days_body.dart, the shared day_calendar.dart); the sick-face icon on the home screen
Rules, Dart port	phone_app/lib/services/sick_day_pool.dart: records {state: sick/cleared, actor}, one HLC per write, never a tombstone
Sync	phone_app/lib/services/sick_day_sync.dart (shared tick: day_pool_sync.dart), Firebase only
Ring path	android/.../SickDays.kt (+ DayCache.kt), read in AlarmReceiver through RingDecision.kt
Stick	StickCheck.kt: verdict sick_day; the streak skips sick days like free days
Pre-alarm sync	PoolSyncAlarm.kt, PoolSyncSchedule.kt, PoolSyncEngine.kt → poolSyncMain → day_pool_refresh.dart

The picker

Same Monday-first grid as the free days, in cat-2 blue (DayMarkColors in ui/theme.dart) rather than the accent gold, under its own title and icon. One tap marks a day sick, another clears it. Today is tappable (unlike the free-day grid); the past is inert. No count, no confirmation.

A date is never in both pools

Each picker syncs the other pool on open and refuses a date it holds, naming the pool: 2026-10-20 is a free day — release it in Free days first. / 2026-10-20 is a sick day — clear it in Sick days first. If the other pool cannot be opened, every mark is refused ("could not check" never counts as "not in it"), as sickdays' ConflictCheckUnavailableError does. free_day_pool.dart itself is untouched: the check lives in the callers, exactly as the Python README prescribes.

The ring

AlarmReceiver asks RingDecision.skip(free, sick). On a sick day it logs sick day: not ringing; re-armed for tomorrow, appends alarm_fired with reason: "sick_day", re-arms and returns: no AlarmService, no RingWatch.markFired, no headless ring_started. The stick's checks at A + 15, boot and watchdog return sick_day for that date, so there is no miss, no streak change and no lockdown; the stakes card says Sick day — no alarm, nothing at stake.

Fail closed. An unreadable or missing cache is "not a sick day" (DayCache), so the phone rings, matching sickdays.is_sick_day().

PC → phone before the ring, with the app closed

sickdays add on the PC writes locally; its sync timer pushes to RTDB. The phone pulls from RTDB. A pre-alarm sync does that pull with no screen open, so a PC mark reaches the native cache before the ring:

• PoolSyncAlarm arms an allow-while-idle exact alarm (request code 1006; inexact fallback if exact alarms are refused, never setAlarmClock, so it is never shown as the next alarm) at the earliest of 21:00 and A − 30 min. It is armed from AlarmScheduler.schedule(), the funnel every arm path uses (boot included), and re-arms itself.
• PoolSyncReceiver holds the broadcast open with goAsync() (it keeps the process out of the cached/frozen state) while PoolSyncEngine runs a headless Flutter engine on poolSyncMain. That pulls both pools and rewrites both native caches through AlarmChannel. Dart says done; a 25 s timeout stops it regardless (the broadcast limit is 60 s).
• The ring decision stays a cache read. A network call inside AlarmReceiver would spend the alarm-clock exemption that lets AlarmService start, and a missed ring cannot be failed closed.

The guarantee is precisely this: a day marked on the PC, and pushed by its sync timer before 21:00 (or before A − 30), is honoured if the phone has network at that slot. The evening slot is the dependable one. The morning slot usually runs in Doze, where an allow-while-idle alarm gets only a short network window. If both fail, the cache keeps its last sync and the phone rings. Launching the app or opening either picker also syncs both pools. The free-day pool rides along, which closes the "PC mark overnight can miss the ring" gap DOCS-free-days.md used to admit.

Known edge: a sick mark that lands after the morning was dismissed does not stop that session's re-rings (REASON_RERING is not gated); no pre-alarm sync runs between A and the session's end anyway.

Checks

• Dart: test/services/sick_day_pool_test.dart (rules + a log written by the real Python package), sick_day_sync_test.dart, day_pool_refresh_test.dart (an RTDB log from the PC reaches setSickDays through runHeadlessPoolSync), test/sick_days_screen_test.dart, test/free_days_sick_conflict_test.dart, test/services/today_stakes_sick_test.dart.
• Kotlin (JVM, android/app/src/test): DayCacheTest, RingDecisionTest, PoolSyncScheduleTest, StickCheckSickTest. Run with cd phone_app/android && ./gradlew :app:testDebugUnitTest (needs local.properties with flutter.sdk=/opt/flutter).
• Cross-language: phone_app/scripts/sick_days_interop/check.sh writes a pool through Dart and reads it with sickdays (Python), failing on any disagreement. Needs SICKDAYS_PYTHON or the sickdays venv.

Do NOT

• Don't fold sick days into FreeDays/isFree, or log them as free_day.
• Don't sync inside AlarmReceiver. Don't tombstone a date to clear it.
• Don't add a count, a reason prompt or a warning. There is no budget.