local-notifications-scheduler

Local Notifications Scheduler

One on-device reminder engine, owned centrally, with a narrow API. The local DB is the source of truth; the OS pending set is a disposable cache. Every scheduling change flows through one pure-then-reconcile path so the whole engine is verifiable off-device. Applies whenever you schedule, cancel, or reason about local notifications.

Read the reference for the task at hand:

• references/notification-gateway-port.md — the port contract, the two adapters, channels/grouping/deep-link payload rules.
• references/scheduler-and-recurrence-rules.md — pure ReminderScheduler.compute diff, recurrence/DST math, deterministic IDs, budgeting, the full test matrix.
• references/platform-boot-exact-alarms-oem.md — boot re-arm, exact-alarm degradation, background-isolate safety, Android manifest/Gradle, the OEM survival matrix.

Run scripts/check-single-fln-import.sh, scripts/check-scheduler-purity.sh, scripts/check-adhoc-schedule-calls.sh, and scripts/check-manifest-permissions.sh before a PR.

Non-negotiable rules

1. The local DB is the ONLY source of truth. The OS pending-notification set is a disposable cache you reconcile against — never the store of record. Every reminder must be reconstructible from the DB alone after process death, reboot, Doze, or restore.
2. Route EVERY scheduling change through one syncNotifications() reconcile entrypoint. Never call gateway.schedule()/cancel() ad hoc from feature or UI code — that path cannot be made idempotent and desyncs the cache.
3. Import flutter_local_notifications in exactly one file — the FLN adapter. Everything else, including all tests, talks to the NotificationGateway port. A grep gate fails the build on any other import.
4. Keep all scheduling math in pure, side-effect-free classes. No plugin calls, no IO, no DateTime.now() inside them — inject a Clock from package:clock: Riverpod code reads it from clockProvider, the pure math takes it as a parameter (never DateTime.now(), never a bespoke ClockService). Purity is what makes off-device unit testing via FakeNotificationGateway possible.
5. Store recurring schedules as wall-clock + recurrence rule, resolve to TZDateTime only at schedule time. Never persist a recurring schedule as a UTC instant — it drifts an hour across every DST boundary. True one-off instants stay UTC epoch millis.
6. Set tz.local at startup (from flutter_timezone). The timezone package defaults to UTC — forget this and every zonedSchedule fires at the wrong local hour.
7. Default to AndroidScheduleMode.inexactAllowWhileIdle (permission-free, pierces Doze). Gate exact firing behind the user-revocable SCHEDULE_EXACT_ALARM via canScheduleExactAlarms() with silent fallback to inexact. Never declare USE_EXACT_ALARM — Play policy restricts it to alarm/timer/calendar apps and risks store rejection.
8. Budget to ~50 pending on iOS (headroom under the silent 64-cap). Sort future instants ascending, take the nearest ~50, refill on every foreground. The 65th+ silently never fires, with no error.
9. Use deterministic IDs derived from reminderId + occurrenceIndex plus a hash of the resolved fire instant and notification content. getPending() exposes only the id, not when — so if the id ignored the fire time, editing a reminder without changing its occurrence (a one-off moved 09:00→14:00, or a daily rule's hour changed) would keep the same id, be skipped by BOTH the cancel and schedule loops, and fire at the OLD time. Folding the resolved TZDateTime (and content) into the id makes an edit produce a NEW id — old id cancelled, new id scheduled. Unchanged input still maps to the same id, so reconcile stays a no-op.
10. The app-foreground reconcile is the reliability backbone. Boot receiver, background ticks, exact-alarm toggle, and OEM survival are all explicitly best-effort. With no server push there is no way to learn a reminder was dropped except the next foreground reconcile diff — that constraint is why this architecture exists, not a gap to paper over.