From 863b94a7d58103021b591463530d098977065da2 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sat, 21 Nov 2026 10:52:10 +0100 Subject: [PATCH] Split PC sick-day docs out of enforcement doc DOCS-wake-enforcement.md had grown to 284 lines and failed the 250-line gate. Todo: 7808ee0a Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- DOCS-sick-days-pc.md | 72 ++++++++++++++++++++++++++++++++++++++++ DOCS-sick-days.md | 2 +- DOCS-wake-enforcement.md | 68 ++----------------------------------- 4 files changed, 76 insertions(+), 68 deletions(-) create mode 100644 DOCS-sick-days-pc.md diff --git a/AGENTS.md b/AGENTS.md index 445d368..4498b0a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,7 +71,7 @@ clock, and everything that is a hard crash or a silent no-ring: does not ring: `AlarmReceiver` checks a native cache Dart rewrites after every mark/release/sync. Picker, cache, fail-closed contract: **`DOCS-free-days.md`**. Sick days (`~/src/utils/sickdays`, never a free day): phone + pre-alarm sync -**`DOCS-sick-days.md`**, PC **`DOCS-wake-enforcement.md`**. +**`DOCS-sick-days.md`**, PC **`DOCS-sick-days-pc.md`**. ## Scheduling — a per-minute timer diff --git a/DOCS-sick-days-pc.md b/DOCS-sick-days-pc.md new file mode 100644 index 0000000..6c79c02 --- /dev/null +++ b/DOCS-sick-days-pc.md @@ -0,0 +1,72 @@ +# Sick days -- PC side (2026-10-16) + +Split out of `DOCS-wake-enforcement.md` (250-line gate). The phone half and +the pool itself: `DOCS-sick-days.md`. + + +A sick day (that does not keep `alarm`, see below) is a date in the shared `sickdays` pool (`~/src/utils/sickdays`): +uncapped, no reason, today or later, and **not a free day** -- its own pool, +its own reason strings (`sick_day` / `sick day`). On a sick day `D` (the +alarm's day, so the RTC asks about *tomorrow* the evening before): + +| piece | on a sick day | +|---|---| +| fallback ring | never starts; a ring in progress stops (`stop_reason` `sick_day`) | +| RTC self-wake | not armed for `D`; an alarm we armed for `D` is disarmed (`rtc_skip` / `rtc_disarmed`, reason `sick day`) | +| trigger | `morning-routine.service` is not started (`sick day`), like a free day | +| workday penalty | never written for `D`; one *issued* on `D` before `D` was marked is deleted (`penalty_cancelled`, `cause: sick_day`) by the next `_session --refresh` or `_rtc --arm` | +| `morning_session.json` | unchanged: it only *grants* exemptions, and every locker stands down on a sick day by its own check | +| audit | RTC / up-by-A / ring / lockdown checks are n/a; a penalty for `D` on disk or a `lockdown_sent` for a miss on `D` is flagged | + +All of it lives behind `wake_alarm/_sick.py`. **Fail closed:** an +unreadable pool, or `sickdays` not importable under `/usr/bin/python`, is +"not sick" -- enforcement runs. + +**Sync.** The decisions read the local pool, and the act modes pull it from +Firebase first (`sickdays.sync_quietly()`), because the sickdays sync timer +alone cannot be trusted at the moment that matters: it is a monotonic +15-minute timer, paused during hibernate and with no `Persistent` catch-up, +so right after the RTC resume the pool can be an interval stale. Pulled: +`_rtc --arm` when the target is a stick day that is not free; the fallback +tick whenever it already goes to the network (`A-5 .. A+45`, and every poll +of a ring in progress, so a day marked sick mid-ring stops it); the day's +first penalty write. The trigger reads only the local file -- the fallback +has pulled from `A-5`. `--dry-run` / `--show` never pull (a pull rewrites +the pool file). + +**Other readers of `workday_penalty.json`** (screen-locker, leetcode-guard) +must treat the file as void when **either** its `issued_date` is a day the +*alarm* stands down on (`sickdays.stands_down(sickdays.LOCKER_ALARM, +date.fromisoformat(issued_date))`) **or** its `penalty_date` is a day *their +own* locker stands down on (`stands_down(LOCKER_WORKOUT, ...)` for +screen-locker, `LOCKER_LEETCODE` for leetcode-guard). `issued_date` covers a +miss at 08:15 marked sick at 14:00 -- the deletion runs on the next RTC tick +(<= 15 min) or the next morning's refresh, and a reader must not depend on +that; the ring day belongs to the alarm switch, the penalty day to whatever +the penalty charges. + +**Keeping the alarm (`sickdays` 0.2.0).** A sick day may keep lockers +(`sickdays add --keep alarm`). Everything in the table above is the single +`alarm` switch (`_sick.alarm_stands_down`): on a sick day that keeps `alarm` +the fallback ring, RTC self-wake, trigger, workday penalty (written, and not +retracted) and audit behave exactly as on a normal stick day. + +**Phone, assumed name:** the phone's `alarm_fired` on a sick day carries +`data.reason = "sick_day"` (by analogy with `free_day`); the audit treats +it as not the morning's ring. + +**A stand-down latches at ring time (fixed 2026-11-16).** On 2026-11-11 the +07:40 ring stood down for a sick day (`alarm_fired reason=sick_day`), the +phone cleared the mark at 11:38, and the 19:31 stick check re-read the cache, +found a normal Wednesday with no dismissal and sent a lockdown. That punished +a day whose alarm never rang, so no dismiss was possible. `AlarmReceiver` now +records the skip (`RingWatch.markSkipped`, a `DateHistory` per reason), and +`StickCheck.decideDay` returns `sick_day`/`free_day` for a latched day even +after a clear. The streak look-back skips it too. A phone that was off at A +latches nothing, so a clear still makes that day a stick day (hole 1). +Tests: `StickCheckSickTest`. + +**Still open: on-device check.** At the next real miss (Tue/Wed/Thu), right +after 09:30 run `adb -s 23181JEGR08034 logcat -d | grep -E +"LOCKDOWN_ACTIVATED|WORKDAY_LOCKDOWN"` (read-only) and confirm +`LOCKDOWN_ACTIVATED` is followed by `WORKDAY_LOCKDOWN`. diff --git a/DOCS-sick-days.md b/DOCS-sick-days.md index fa0dbf2..7a5ca8e 100644 --- a/DOCS-sick-days.md +++ b/DOCS-sick-days.md @@ -10,7 +10,7 @@ nothing ring-related is recorded -- **unless the day keeps the alarm**. Since sickdays 0.2.0 a sick day carries a per-locker `keep` set (README "keep (0.2.0)"): a kept locker behaves exactly as on a normal day, every other one stands down. This app is the `alarm` locker (ring, PC fallback ring, RTC -self-wake, missed-alarm penalty / stick, morning routine). It is **not** a free day: separate pool, +self-wake, missed-alarm penalty / stick, morning routine; PC side: `DOCS-sick-days-pc.md`). 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`. diff --git a/DOCS-wake-enforcement.md b/DOCS-wake-enforcement.md index b7c26b3..74ca0ea 100644 --- a/DOCS-wake-enforcement.md +++ b/DOCS-wake-enforcement.md @@ -97,72 +97,8 @@ wake-alarm, todo) — narrower than the night list. ### Sick days (PC side, 2026-10-16) -A sick day (that does not keep `alarm`, see below) is a date in the shared `sickdays` pool (`~/src/utils/sickdays`): -uncapped, no reason, today or later, and **not a free day** -- its own pool, -its own reason strings (`sick_day` / `sick day`). On a sick day `D` (the -alarm's day, so the RTC asks about *tomorrow* the evening before): - -| piece | on a sick day | -|---|---| -| fallback ring | never starts; a ring in progress stops (`stop_reason` `sick_day`) | -| RTC self-wake | not armed for `D`; an alarm we armed for `D` is disarmed (`rtc_skip` / `rtc_disarmed`, reason `sick day`) | -| trigger | `morning-routine.service` is not started (`sick day`), like a free day | -| workday penalty | never written for `D`; one *issued* on `D` before `D` was marked is deleted (`penalty_cancelled`, `cause: sick_day`) by the next `_session --refresh` or `_rtc --arm` | -| `morning_session.json` | unchanged: it only *grants* exemptions, and every locker stands down on a sick day by its own check | -| audit | RTC / up-by-A / ring / lockdown checks are n/a; a penalty for `D` on disk or a `lockdown_sent` for a miss on `D` is flagged | - -All of it lives behind `wake_alarm/_sick.py`. **Fail closed:** an -unreadable pool, or `sickdays` not importable under `/usr/bin/python`, is -"not sick" -- enforcement runs. - -**Sync.** The decisions read the local pool, and the act modes pull it from -Firebase first (`sickdays.sync_quietly()`), because the sickdays sync timer -alone cannot be trusted at the moment that matters: it is a monotonic -15-minute timer, paused during hibernate and with no `Persistent` catch-up, -so right after the RTC resume the pool can be an interval stale. Pulled: -`_rtc --arm` when the target is a stick day that is not free; the fallback -tick whenever it already goes to the network (`A-5 .. A+45`, and every poll -of a ring in progress, so a day marked sick mid-ring stops it); the day's -first penalty write. The trigger reads only the local file -- the fallback -has pulled from `A-5`. `--dry-run` / `--show` never pull (a pull rewrites -the pool file). - -**Other readers of `workday_penalty.json`** (screen-locker, leetcode-guard) -must treat the file as void when **either** its `issued_date` is a day the -*alarm* stands down on (`sickdays.stands_down(sickdays.LOCKER_ALARM, -date.fromisoformat(issued_date))`) **or** its `penalty_date` is a day *their -own* locker stands down on (`stands_down(LOCKER_WORKOUT, ...)` for -screen-locker, `LOCKER_LEETCODE` for leetcode-guard). `issued_date` covers a -miss at 08:15 marked sick at 14:00 -- the deletion runs on the next RTC tick -(<= 15 min) or the next morning's refresh, and a reader must not depend on -that; the ring day belongs to the alarm switch, the penalty day to whatever -the penalty charges. - -**Keeping the alarm (`sickdays` 0.2.0).** A sick day may keep lockers -(`sickdays add --keep alarm`). Everything in the table above is the single -`alarm` switch (`_sick.alarm_stands_down`): on a sick day that keeps `alarm` -the fallback ring, RTC self-wake, trigger, workday penalty (written, and not -retracted) and audit behave exactly as on a normal stick day. - -**Phone, assumed name:** the phone's `alarm_fired` on a sick day carries -`data.reason = "sick_day"` (by analogy with `free_day`); the audit treats -it as not the morning's ring. - -**A stand-down latches at ring time (fixed 2026-11-16).** On 2026-11-11 the -07:40 ring stood down for a sick day (`alarm_fired reason=sick_day`), the -phone cleared the mark at 11:38, and the 19:31 stick check re-read the cache, -found a normal Wednesday with no dismissal and sent a lockdown. That punished -a day whose alarm never rang, so no dismiss was possible. `AlarmReceiver` now -records the skip (`RingWatch.markSkipped`, a `DateHistory` per reason), and -`StickCheck.decideDay` returns `sick_day`/`free_day` for a latched day even -after a clear. The streak look-back skips it too. A phone that was off at A -latches nothing, so a clear still makes that day a stick day (hole 1). -Tests: `StickCheckSickTest`. - -**Still open: on-device check.** At the next real miss (Tue/Wed/Thu), right -after 09:30 run `adb -s 23181JEGR08034 logcat -d | grep -E -"LOCKDOWN_ACTIVATED|WORKDAY_LOCKDOWN"` (read-only) and confirm -`LOCKDOWN_ACTIVATED` is followed by `WORKDAY_LOCKDOWN`. +A sick day stands down the fallback ring, RTC self-wake, trigger, workday +penalty and audit: **`DOCS-sick-days-pc.md`**. ### Escape hatch (until 2026-10-15 inclusive)