"""The PC fallback alarm's rule, as one pure function. ``DOCS-wake-enforcement.md``'s table, first match wins, inside ``A - 5 min .. A + 45 min`` on a day that is neither free nor sick: ========================================================= ================== escape recorded for today, or a session started today do not ring / stop ring already ran 30 min today (``FALLBACK_RING_CAP``) never again today ``now >= A + 2 min`` and no ``ring_started`` for today ring: phone_silent ``now >= A + 15 min`` (``SESSION_NONE_GRACE``) ring: no_session ========================================================= ================== A **bypass** comes before the table (2026-11-22): a ``bypass`` phone event today (the app paused, its admin removed, a permission revoked, the ring killed) with no newer ``dismissed`` rings ``bypass`` for 30 minutes from the event, ignoring the window, a started session, a final reason and the day's own cap. Only a free or sick day, or an escape, stands it down. The window gates *starting* a ring only. A ring that already started today and has not hit its cap is judged by the table alone, so a ringing process killed by a hibernate resumes after the resume instead of going quiet because the clock moved past the window. Firebase being unreachable is modelled by the caller as "no ping, no session, no escape": fail toward ringing. """ from __future__ import annotations from dataclasses import dataclass from datetime import date, datetime, time, timedelta from typing import TYPE_CHECKING from wake_alarm._constants import ( FALLBACK_ALARM_HOUR, FALLBACK_PHONE_SILENT_AFTER, FALLBACK_RING_CAP, FALLBACK_WINDOW_END, SESSION_NONE_GRACE, ) if TYPE_CHECKING: from wake_alarm._fallback_latch import Latch from wake_alarm._sync import Alarm # The tick starts looking (and fetching) this long before the alarm, so the # first decision of the day is logged before anything can ring. FALLBACK_WINDOW_START: timedelta = timedelta(minutes=5) # While ringing, how often the stop conditions are re-read from Firebase. FALLBACK_POLL_SECONDS: float = 20.0 # Reasons, as they appear in events.jsonl and fallback_ring.json. FREE_DAY = "free_day" SICK_DAY = "sick_day" OUTSIDE_WINDOW = "outside_window" ESCAPE = "escape" SESSION_STARTED = "session_started" CAP = "cap" PHONE_SILENT = "phone_silent" NO_SESSION = "no_session" WAITING = "waiting" BYPASS = "bypass" BYPASS_CLEARED = "bypass_cleared" # How long after A the tick keeps reading the phone for a bypass. The morning # session's last cutoff is 11:00 and A is never later than 08:00 (07:00 at # the end of the ramp), so A + 4 h covers every live ring and session. BYPASS_WATCH: timedelta = timedelta(hours=4) # Once seen, these hold for the rest of the day even if Firebase later stops # answering: an unreachable backend fails toward ringing, but never toward # ringing at someone already known to be up. FINAL_REASONS: frozenset[str] = frozenset({ESCAPE, SESSION_STARTED, CAP}) @dataclass(frozen=True) class Facts: """Everything one decision needs; the caller gathers it. ``settled`` is a final reason (``FINAL_REASONS``) already seen today. """ now: datetime alarm_at: datetime free_day: bool sick_day: bool = False escaped: bool = False session_started: bool = False ring_started: bool = False latch: Latch | None = None settled: str | None = None # The newest bypass today not followed by a dismiss; None = none live. bypass_at: datetime | None = None @dataclass(frozen=True) class Decision: """Ring or not, and the one-word reason either way.""" ring: bool reason: str def alarm_instant(alarm: Alarm, day: date) -> datetime: """Today's ``A``: the alarm on ``day``, clamped to the 08:00 baseline. Built naive and localised afterwards, like ``_trigger._fire_window``, so the offset is the one in force at the alarm, not at the tick. """ hour, minute = min((alarm.hour, alarm.minute), (FALLBACK_ALARM_HOUR, 0)) return datetime.combine(day, time(hour, minute)).astimezone() def _ring_started_today(latch: Latch | None) -> bool: """Whether today's fallback has already rung at all.""" return latch is not None and latch.started() is not None def in_window(now: datetime, alarm_at: datetime, latch: Latch | None) -> bool: """Whether the table's rows may start (or resume) a ring now.""" if _ring_started_today(latch): return True return alarm_at - FALLBACK_WINDOW_START <= now < alarm_at + FALLBACK_WINDOW_END def needs_facts(now: datetime, alarm_at: datetime, latch: Latch | None) -> bool: """Whether this tick must fetch the phone's state at all. The window, or the bypass watch after it (``BYPASS_WATCH``). Outside both the answer is already ``outside_window``, so the per-minute tick stays off the network. """ if in_window(now, alarm_at, latch): return True return alarm_at - FALLBACK_WINDOW_START <= now < alarm_at + BYPASS_WATCH def is_capped(facts: Facts) -> bool: """Whether today's ring has used its 30 minutes.""" latch = facts.latch if latch is None: return False if latch.stop_reason == CAP: return True started = latch.started() return started is not None and facts.now >= started + FALLBACK_RING_CAP def day_off(facts: Facts) -> str | None: """``free_day`` / ``sick_day`` when today rings nothing at all.""" if facts.free_day: return FREE_DAY if facts.sick_day: return SICK_DAY return None def stop_reason(facts: Facts) -> str | None: """Why a ring in progress must stop now, or None to keep ringing. Only the contract's three stop conditions (plus a day that turned free or sick): a phone that comes back on mid-ring does not silence the PC -- getting up does. """ off = day_off(facts) if off is not None: return off if facts.settled in FINAL_REASONS: return facts.settled if facts.escaped: return ESCAPE if facts.session_started: return SESSION_STARTED if is_capped(facts): return CAP return None def bypass_stop_reason(facts: Facts) -> str | None: """Why a bypass ring must stop now, or None while the bypass stands.""" off = day_off(facts) if off is not None: return off if facts.escaped: return ESCAPE if facts.bypass_at is None: return BYPASS_CLEARED if facts.now >= facts.bypass_at + FALLBACK_RING_CAP: return CAP return None def decide(facts: Facts) -> Decision: """A live bypass first, then the table above; first match wins.""" off = day_off(facts) if off is not None: return Decision(ring=False, reason=off) if facts.bypass_at is not None and bypass_stop_reason(facts) is None: return Decision(ring=True, reason=BYPASS) return _decide_table(facts) def _decide_table(facts: Facts) -> Decision: """The table's rows, on a day that is neither off nor bypassed.""" if not in_window(facts.now, facts.alarm_at, facts.latch): return Decision(ring=False, reason=OUTSIDE_WINDOW) stop = stop_reason(facts) if stop is not None: return Decision(ring=False, reason=stop) if facts.now >= facts.alarm_at + FALLBACK_PHONE_SILENT_AFTER and not ( facts.ring_started ): return Decision(ring=True, reason=PHONE_SILENT) if facts.now >= facts.alarm_at + SESSION_NONE_GRACE: return Decision(ring=True, reason=NO_SESSION) return Decision(ring=False, reason=WAITING)