RFC 0003: SalahAlerts

[omar-hanafy]

Comments on RFC 0003, the contract of SalahAlerts: the alert planner and its notification budget, the scheduler's stable request identities and read-back, and the in-process engine for apps that keep running. An outside API review of this RFC is still pending.

The RFC stays open to findings from apps that use SalahKit until 1.0 (STANDARD.md, Releases). If an API doesn't fit your app, say what the app does, what it needs and what you tried. Changes to the API follow the RFC process in CONTRIBUTING.md.

[omar-hanafy]

RFC 0003 amendment for SalahKit 0.4.0

2. 0.4.0 amendment: handled occurrences after a clock rollback (SalahAlerts: a clock set back re-requests alerts that already fired #16). The engine retains its internal report-time record for one day after reporting, extended to max(86400, atTimeGrace + 60, reminderGrace + 60) seconds for longer graces. Records are written before onDue; each due check drops records at that age or older and their notification-exclusion marks.

   excludeHandledOccurrencesFromNotifications() marks only the unexpired occurrences already reported, without checking or delivering alerts. Consumers call it on an explicit clock-change event before update or resync. notificationExclusions(at:) returns those retained marks plus retained keys whose report time is after the supplied planning instant (nil uses the engine clock). Every replan uses this query, including ordinary updates, wakes, activation and time-zone changes. Those ordinary events do not mark new exclusions. Newly reported early alerts remain eligible, and excluded alerts stay excluded across later replans. The query and marking operation disregard expired records even before a due check prunes them.

   AlertPlanner.notificationPlan(_:from:budget:excluding:) accepts Set<AlertOccurrenceID> = []. It excludes every supplied exact occurrence before both selection phases, consumes no allowance and creates no coverage hole. Source gaps still shorten coverage. A changed fire date or namespace is a different occurrence. The empty default preserves existing call behavior. Both Salah and Examples/MenuBar use the engine's two methods; neither maintains an app-owned handled record.

   The record proves engine reporting, not system delivery. A clock-change exclusion can remove an early-reported request that has not reached its system delivery time. State does not survive relaunch or pruning. Due delivery stays after the latest apply; operating-system presentation and elapsed time during asynchronous apply/deliver remain outside this record's guarantees.

   The maintainer waived the one-week comment window for this pre-1.0 addition. Later API changes follow CONTRIBUTING's RFC process.

3. 0.4.0 amendment: rollback after a system delivery (Prevent replay when a clock rollback lands inside the early-report window #18). A report at T − 1 second, system delivery at T, and rollback to T − 0.5 seconds must not reinstall the delivered request. Comparing only the new instant with the report time missed this case. A one-plan exclusion also failed when an ordinary refresh followed the clock event. Hosted MenuBar and Salah regressions reproduce the pending-to-delivered transition, rollback, ordinary update and wake; the engine-owned retained mark addresses the whole sequence. Other tests preserve ordinary early pending requests, newly due early reports during a clock event, changed occurrences and retention limits.

   The nine new alerts/handled.json vectors use occurrence-only query.excluding. They pin exact-key exclusion, capacity in both selection phases, full coverage when all alerts are excluded, early-window and at-fire-date exclusion, changed dates, foreign namespaces, reminders and gaps. Five new alerts/retained.json cases add query.engineSteps: a manual-clock sequence of update, resync, mark, idle and relaunch operations. An independent Python model calculates the final exclusion set, callback report history and plan. Cases pin marks across ordinary checks, marking without delivery, newly due early reports, expiry before another check and relaunch. Both the exact exclusion set and report history are asserted, so an unwanted mark-time report or an expired key outside the plan's range cannot pass unnoticed. Every original alert/reconciliation vector remains unchanged. These added cases encode the changed exclusion lifecycle; compiled DocC examples exercise the same public ordering.

   The maintainer waived the one-week comment window for these pre-1.0 changes. Later API changes follow CONTRIBUTING's RFC process.

Implementation and verification are tracked in PR #17.