From f3c5ded6872dbb13e36ac22be8c8b9e767f2a803 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Wed, 29 Jul 2026 14:38:05 +0200 Subject: [PATCH] docs(01-18): complete occurrence identity implementation - document reminder and rolling due fixes across shared consumers - record green unit and real PostgreSQL regression coverage --- .../01-18-SUMMARY.md | 130 ++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 .planning/phases/01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability/01-18-SUMMARY.md diff --git a/.planning/phases/01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability/01-18-SUMMARY.md b/.planning/phases/01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability/01-18-SUMMARY.md new file mode 100644 index 000000000..3d4bfc711 --- /dev/null +++ b/.planning/phases/01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability/01-18-SUMMARY.md @@ -0,0 +1,130 @@ +--- +phase: 01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability +plan: "18" +subsystem: medication-scheduling +tags: [medications, recurrence, reminders, occurrence-identity, postgres] + +requires: + - phase: 01-11 + provides: RED reminder and rolling-overdue occurrence contracts +provides: + - Cross-midnight reminder lookup and dedup keyed to the canonical scheduled occurrence + - Rolling prior-occurrence projection bounded by the existing actionable band + - Schedule/era-aware exact resolution with retry-safe shared consumer state +affects: [issue-664, medication-reminders, rolling-recurrence, medication-list, dashboard] + +tech-stack: + added: [] + patterns: + - canonical occurrence identity carries schedule ID plus exact scheduled instant + - display-band projection is separate from retrospective compliance thresholds + - server list state prevents client clock-window rebinding + +key-files: + created: [] + modified: + - src/lib/jobs/reminder/medication-reminder-check.ts + - src/lib/medications/scheduling/recurrence.ts + - src/lib/medications/scheduling/next-due.ts + - src/lib/medications/scheduling/band-minter.ts + - src/lib/medications/list-read.ts + +key-decisions: + - "Reminder suppression and dedup derive from the selected occurrence local date, never the worker tick date." + - "Open rolling occurrences opt into display-band minting without changing the half-cycle compliance denominator." + - "Resolved rolling skips and auto-misses advance on the existing cadence grid without becoming intake anchors." + - "Existing canonical intake upsert/retry behavior was retained because its real-Postgres controls already passed." + +patterns-established: + - "Occurrence identity: scheduleId + scheduled instant, with action time used for era isolation." + - "Consumer authority: prior rolling due state is projected once by the server and not reconstructed from today's wall clock." + +requirements-completed: [REM-01, REM-02, REM-03, REM-04, REM-05, MED-01, MED-02, MED-03, MED-04, MED-05, MED-06] + +duration: 10min +completed: 2026-07-29 +--- + +# Phase 01 Plan 18: Canonical Medication Occurrence Identity Summary + +**Canonical schedule-and-instant identity now survives reminder midnight boundaries and keeps unresolved rolling doses visible through their existing actionable band across every medication consumer.** + +## Performance + +- **Duration:** 10 min +- **Started:** 2026-07-29T12:27:25Z +- **Completed:** 2026-07-29T12:36:57Z +- **Tasks:** 3 +- **Files modified:** 6 + +## Accomplishments + +- Fixed issue #664’s worker-day mismatch by selecting canonical recurrence occurrences, widening the action lookup only to eligible cross-midnight windows, and deriving dedup/notification metadata from the occurrence itself. +- Removed the rolling post-midnight gap by retaining the prior occurrence identity and opting display-due banding into the open rolling slot without changing weekly clinical windows or compliance’s half-cycle threshold. +- Added schedule and era identity to exact resolved marks, allowing taken/skipped/auto-missed state to suppress one occurrence while sibling schedules, replacement eras, and future grid occurrences remain independent. +- Kept list, Dashboard, GLP-1 card, and take-all on the same persisted occurrence; exact intake, concurrent retries, tombstones, and sibling medications converge without duplicate live rows or false already-taken behavior. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Carry scheduled occurrence identity through reminder lookup and dedup** - `c0af97ce4` (fix) +2. **Task 2: Keep unresolved rolling occurrence through its band** - `2de9bccf9` (fix) +3. **Task 3: Use one due result for reads, projection, and intake** - `840e47fda` (fix) + +Supporting cleanup: + +- `0ae9165aa` - repository formatting for the occurrence identity changes + +## Files Created/Modified + +- `src/lib/jobs/reminder/medication-reminder-check.ts` - Selects an active canonical occurrence across midnight and uses its exact instant/date for suppression, dedup, minting, and notification metadata. +- `src/lib/medications/scheduling/recurrence.ts` - Carries schedule identity, retains the immediate rolling occurrence across day changes, and advances resolved rolling grid occurrences. +- `src/lib/medications/scheduling/next-due.ts` - Resolves by schedule/era identity, selects open overdue bands, and rejects closed stale rolling occurrences. +- `src/lib/medications/scheduling/band-minter.ts` - Allows display consumers to include an open rolling occurrence while retrospective compliance retains its existing threshold. +- `src/lib/medications/list-read.ts` - Exposes the due schedule ID and prevents a prior rolling occurrence from being rebound to today’s matching clock window. + +## Decisions Made + +- A prior reminder occurrence is searched only when its own resolved window crosses into the current local day; ordinary stale yesterday slots do not begin reminding again. +- `Occurrence.scheduleId` is the canonical owner. Optional schedule/action metadata on persisted resolution marks preserves backward compatibility while enabling exact sibling and era isolation where attribution provides identity. +- A skipped or auto-missed rolling occurrence advances to the next cadence-grid occurrence but does not alter `lastIntakeAt`; only a real take re-anchors rolling cadence. +- The existing intake upsert already passed real concurrent/retry and unrelated-row tests, so no route or schema change was warranted. + +## Deviations from Plan + +None - plan executed within the listed production boundaries. Files whose existing implementation already satisfied the green contract were verified and left unchanged. + +## Verification + +- **Broad focused unit cluster:** 21 files, 388 tests passed. + - Includes every scheduling unit suite, reminder worker/dedup, intake route, medication-card next-due, and take-all. +- **Real PostgreSQL regression cluster:** 2 files, 8 tests passed. + - Cross-midnight reminder: 2/2. + - Rolling overdue consumers and intake concurrency/isolation: 6/6. +- **ESLint:** Passed for all eight Plan 01-18 production files. +- **Prettier:** Passed for all eight Plan 01-18 production files. +- **TypeScript:** No Plan 01-18 errors. Repository-wide `pnpm typecheck` remains non-zero only because concurrent Google Health RED tests reference `sync-progress` and status-route production modules that have not landed yet. + +## Issues Encountered + +- Repository-wide type checking is temporarily blocked by concurrent Plan 01-13 Google Health work. The remaining diagnostics are confined to its test files; all occurrence-identity production files are clean. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- REM-01 through REM-04 and MED-01 through MED-06 are technically closed by green unit and real-persistence regressions. +- REM-05 remains the stated release-process constraint: issue #664 should stay open until reporter confirmation. +- No migration, package, client fallback, or clinical band widening was introduced. + +## Self-Check: PASSED + +- All 6 claimed files exist. +- All 4 implementation/supporting commits exist. + +--- +*Phase: 01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability* +*Completed: 2026-07-29*