99 lines
6.1 KiB
Markdown
99 lines
6.1 KiB
Markdown
---
|
|
phase: quick-260610-hbu
|
|
verified: 2026-06-10T12:39:30Z
|
|
status: passed
|
|
score: 5/5 must-haves verified
|
|
overrides_applied: 0
|
|
---
|
|
|
|
# Quick Task 260610-hbu: Reminder Scheduler Resilience Verification Report
|
|
|
|
**Task Goal:** Make the Phase 5 reminder scheduler resilient to missed/late cron ticks — catch-up scan + per-uid exactly-once dedup
|
|
**Verified:** 2026-06-10T12:39:30Z
|
|
**Status:** passed
|
|
**Re-verification:** No — initial verification
|
|
|
|
---
|
|
|
|
## Goal Achievement
|
|
|
|
### Observable Truths
|
|
|
|
| # | Truth | Status | Evidence |
|
|
|---|-------|--------|---------|
|
|
| 1 | A shared timed event in (now, now+16min] fires on the next scan even after a missed/late tick (catch-up). | VERIFIED | `gt(calendarEvents.dtstartUtc, now)` at line 103; lower bound is `now`, not `now+14min`. Any scan while event is still future will find it. MISSED-TICK-RECOVERY test fires at 8-min lead. |
|
|
| 2 | A given event fires EXACTLY ONCE across all scans while in the catch-up window — no cross-tick double-fire. | VERIFIED | `sentReminders` is `Map<string, number>` keyed on bare uid (line 47); `if (sentReminders.has(uid)) continue` at line 145. SINGLE-FIRE test asserts `dispatchPush` called exactly once across 3 consecutive ticks. |
|
|
| 3 | An event whose dtstart has already passed (dtstart <= now) does NOT trigger a reminder. | VERIFIED | `gt(calendarEvents.dtstartUtc, now)` at line 103 excludes already-started events at the DB level. "already-started" test mocks empty rows, asserts 0 dispatches. |
|
|
| 4 | Notification body reflects actual lead time (e.g. "Starts in 8 min"), guarded to minimum 1. | VERIFIED | Line 150: `const minutes = Math.max(1, Math.round((event.dtstartUtc.getTime() - now.getTime()) / 60000))` then `body: \`Starts in ${minutes} min\`` at line 156. Not hardcoded. |
|
|
| 5 | Existing Phase-5 behaviours stay green: isShared-only (D-05), allDay excluded (D-07), always-visible notification (D-11), empty push_subscriptions -> zero sends/no crash (D-16), per-event and per-sub error isolation (T-05-18/T-05-19). | VERIFIED | All present in source (lines 101-102 for D-05/D-07; line 98 for D-11 via dispatchPush; lines 141-186 for T-05-18/19 try/catch isolation). Tests for D-05, D-07, D-16, T-05-19 all pass (10/10). |
|
|
|
|
**Score:** 5/5 truths verified
|
|
|
|
---
|
|
|
|
### Required Artifacts
|
|
|
|
| Artifact | Expected | Status | Details |
|
|
|----------|----------|--------|---------|
|
|
| `apps/api/src/broker/reminderScheduler.ts` | Resilient catch-up scan with per-uid exactly-once dedup, `runReminderCheck` exported | VERIFIED | 213 lines; contains `runReminderCheck`, `startReminderScheduler`; `Map<string, number>` dedup; `gt` lower bound; lead-accurate body |
|
|
| `apps/api/tests/broker/reminderScheduler.test.ts` | Tests covering single-fire, missed-tick recovery, already-started exclusion, plus retained Phase-5 behaviours | VERIFIED | 409 lines; contains "SINGLE-FIRE", "MISSED-TICK-RECOVERY", "already-started", D-05/D-07/D-16/WR-01/CR-01/T-05-19 tests |
|
|
|
|
---
|
|
|
|
### Key Link Verification
|
|
|
|
| From | To | Via | Status | Details |
|
|
|------|----|-----|--------|---------|
|
|
| `reminderScheduler.ts` | `calendarEvents.dtstartUtc` | `WHERE gt(now) AND lte(now+16min)` | VERIFIED | Line 103: `gt(calendarEvents.dtstartUtc, now)`. Line 104: `lte(calendarEvents.dtstartUtc, windowEnd)`. |
|
|
| `reminderScheduler.ts` | `dispatchPush` | fan-out per subscription, then mark uid sent | VERIFIED | Lines 163-174: per-sub loop calling `await dispatchPush(sub, notification)`. Line 179: `sentReminders.set(uid, ...)` after the fan-out loop (WR-01 preserved). |
|
|
|
|
---
|
|
|
|
### Behavioral Spot-Checks
|
|
|
|
| Behavior | Command | Result | Status |
|
|
|----------|---------|--------|--------|
|
|
| TypeScript compilation (strict) | `pnpm --filter @familysync/api typecheck` | exit 0, no output | PASS |
|
|
| All 10 reminderScheduler tests pass | `pnpm --filter @familysync/api exec vitest run tests/broker/reminderScheduler.test.ts` | 1 file passed, 10/10 tests passed | PASS |
|
|
| `gt(dtstartUtc, now)` lower bound present | `grep -n "gt(" reminderScheduler.ts` | line 103: `gt(calendarEvents.dtstartUtc, now)` | PASS |
|
|
| `gte` import/usage removed | `grep -n "gte" reminderScheduler.ts` | no matches | PASS |
|
|
| `minuteBucket` variable fully removed | `grep -n "minuteBucket" reminderScheduler.ts` | only in comments, no variable | PASS |
|
|
| Dedup store is `Map<string, number>` keyed by uid | `grep -n "Map" reminderScheduler.ts` | line 47: `new Map<string, number>()` | PASS |
|
|
| Lead-accurate body with Math.max guard | `grep -n "Math.max" reminderScheduler.ts` | line 150: `Math.max(1, Math.round(...))` | PASS |
|
|
| WR-01 mark-after-dispatch preserved | `grep -n "sentReminders.set" reminderScheduler.ts` | line 179: after fan-out loop | PASS |
|
|
| CR-01 started-event pruning | `grep -n "dtstartMs" reminderScheduler.ts` | lines 192-194: prune on `dtstartMs <= now.getTime()` | PASS |
|
|
| Required test names present | grep for SINGLE-FIRE, MISSED, already-started in test file | all found at lines 178, 214, 119 | PASS |
|
|
|
|
---
|
|
|
|
### Anti-Patterns Found
|
|
|
|
None. No TBD/FIXME/XXX markers in modified files. No hardcoded empty data. No stubs.
|
|
|
|
The two `minuteBucket` occurrences at lines 42 and 142 of `reminderScheduler.ts` are comment text only (no variable), correctly documenting the old scheme for historical context — not a stub indicator.
|
|
|
|
---
|
|
|
|
### Human Verification Required
|
|
|
|
None. All must-haves are verifiable programmatically and confirmed by running commands.
|
|
|
|
---
|
|
|
|
## Gaps Summary
|
|
|
|
No gaps. All 5 must-have truths are VERIFIED against the actual codebase:
|
|
|
|
- Catch-up window implemented: `gt(dtstartUtc, now)` lower bound (not `gte(now+14min)`) confirmed in source and tested.
|
|
- Per-uid exactly-once dedup: `Map<string, number>` keyed on bare uid confirmed; `minuteBucket` variable fully absent.
|
|
- Already-started exclusion: strict `gt` lower bound confirmed; test coverage present.
|
|
- Lead-accurate body: `Math.max(1, Math.round(...))` formula confirmed in source.
|
|
- Phase-5 decisions preserved: D-05/D-07/D-11/D-12/D-16/T-05-18/T-05-19/WR-01/CR-01 all present in source and tested.
|
|
- Typecheck: exit 0.
|
|
- Test suite: 10/10 passing, including the three required new tests (SINGLE-FIRE, MISSED-TICK-RECOVERY, already-started exclusion).
|
|
|
|
---
|
|
|
|
_Verified: 2026-06-10T12:39:30Z_
|
|
_Verifier: Claude (gsd-verifier)_
|