From 182d15747d8988c37c67e8ea44266e6ec9499c89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Thu, 21 May 2026 18:17:39 +0200 Subject: [PATCH] docs(planning): W-RECONCILE-INSIGHTS v1.4.41 phase report Captures the helper extract + 6 sibling-route wire + cache-shape reconcile + test pins. Notes the medication-compliance stub-row recogniser fix and the pulse-status-timeout assertion flip as risk callouts. --- .../phase-W-RECONCILE-INSIGHTS-report.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 .planning/phase-W-RECONCILE-INSIGHTS-report.md diff --git a/.planning/phase-W-RECONCILE-INSIGHTS-report.md b/.planning/phase-W-RECONCILE-INSIGHTS-report.md new file mode 100644 index 000000000..6039a262c --- /dev/null +++ b/.planning/phase-W-RECONCILE-INSIGHTS-report.md @@ -0,0 +1,161 @@ +# W-RECONCILE-INSIGHTS — v1.4.41 phase report + +## Goal + +Close the last architectural-correctness High before the v1.4.41 tag: +collapse the duplicated 40-line `auditLog.create` timeout-stub block +into a single shared helper, refactor the existing call-site +(`bmi-status.ts`) onto it, and wire the six remaining sibling status +routes to the same persist path so every route shares one shape on +provider stall. + +## Branch + commits + +- Branch: `worktree-agent-a4b70eb08bcc2d056` (worktree branched from + `develop` at `a1bfc3b4 docs(planning): v1.4.41 marathon handoff + for fresh session`). +- Pushed to origin (see end of report). +- Commits added: + - `9584dc40 refactor(insights): extract shared timeout-stub persist helper` + - `d782f65a perf(insights): wire six sibling status routes to the shared timeout-stub helper` + +## Files touched + +### Helper (new) + +- `src/lib/insights/persist-timeout-stub.ts` — exports + `persistTimeoutStubAndReturn(input)` returning the standard + `{ hasProvider: true; text; cached: true; updatedAt }` envelope. + Body is byte-equivalent to the previous inline block in + `bmi-status.ts` (today's `dateKey`, `locale`, `text`, + `providerType`, `model: "timeout-stub"`, `tokensUsed: null`, + `timeout: true`; best-effort `try/catch`). + +### Routes refactored to use the helper (7 total) + +- `src/lib/insights/bmi-status.ts` — replaced the 45-line inline + block with a 7-line return. +- `src/lib/insights/blood-pressure-status.ts` — new wire, was a bare + fallback before. +- `src/lib/insights/weight-status.ts` — new wire, was bare. +- `src/lib/insights/general-status.ts` — new wire. +- `src/lib/insights/pulse-status.ts` — new wire; updated the stale + "fallback is NOT persisted" comment. +- `src/lib/insights/mood-status.ts` — new wire. +- `src/lib/insights/medication-compliance-status.ts` — new wire with + shape mapping (route returns `{ summary, medications: [] }` so the + helper is called for the persist side-effect and `summary` is + mapped from `text` on the way out). Also extended its cache-read + block to recognise the stub envelope (`dateKey + timeout: true + + text`) so the second-mount short-circuit fires on the same row + shape the helper writes. + +### Tests added / updated + +- `src/lib/insights/__tests__/blood-pressure-status.test.ts` — new + describe block: persist-on-timeout + short-circuit-on-stub. +- `src/lib/insights/__tests__/weight-status.test.ts` — same pair. +- `src/lib/insights/__tests__/general-status.test.ts` — same pair. +- `src/lib/insights/__tests__/mood-status.test.ts` — same pair. +- `src/lib/insights/__tests__/medication-compliance-status.test.ts` + — persist-on-timeout asserts the helper-shaped row + the + `{summary, medications: []}` mapped return shape; short-circuit + pinned against the new stub-recogniser branch. +- `src/lib/insights/__tests__/pulse-status.test.ts` — added the + short-circuit-on-stub case (the persist arm was already covered + by the existing dedicated file below). +- `src/lib/insights/__tests__/pulse-status-timeout.test.ts` — + flipped the old "does NOT persist" assertion (legacy contract) + to the new "persists exactly one stub row with `timeout: true` + + `model: timeout-stub`" assertion. The route now matches BP / + weight / BMI; the legacy comment in the file was rewritten too. + +The existing `bmi-status.ts` tests still pass after the refactor +(helper extraction preserves behaviour; verified, not rewritten). + +## Helper interface + +```ts +export async function persistTimeoutStubAndReturn(input: { + userId: string; + cacheAction: string; + todayKey: string; + locale: string; + providerType: string; + stubText: string; +}): Promise<{ + hasProvider: true; + text: string; + cached: true; + updatedAt: string | null; +}>; +``` + +`updatedAt` is `null` when the `auditLog.create` itself fails +(best-effort persist); the user-facing `text` always renders. + +## Quality gates + +- `pnpm typecheck`: clean (no new errors). +- `pnpm lint`: clean (only the 5 pre-existing warnings on + `src/app/insights/page.tsx` + `src/lib/analytics/summaries-slice.ts` + which are not in scope). +- `pnpm test --run src/lib/insights`: **155 / 155 passed** (was + 144 before; +11 new persist/short-circuit cases across the 6 + sibling routes + the pulse-status-timeout flip). + +Full suite (`pnpm test --run`) was also exercised; the only +failure is the pre-existing `dashboard-suspense-boundaries.test.ts` +red on develop tip (verified by stashing the worktree changes and +re-running — same failure). Not in scope for this wave. + +## Risk callouts / reconcile notes + +1. **medication-compliance cache-shape divergence (resolved + inline).** The route stores `{summary, medications}` in its + audit-log row, not `{text}`. A naive wire would have written a + helper-shaped stub that the route's cache-read block could not + recognise — defeating the entire short-circuit purpose. Fix + landed in the same commit: the route's cache-read block now + recognises both shapes (canonical `summary + medications` for + real assessments + `text + timeout: true` for stubs). Test + pins both branches. + +2. **pulse-status-timeout legacy assertion.** The pre-existing + `pulse-status-timeout.test.ts` asserted + `prisma.auditLog.create` was **never** called on timeout — a + sentinel encoding the v1.4.28 "do not poison tomorrow's cache" + contract. The v1.4.37 stub pattern reversed that decision (the + stub IS the way to NOT poison tomorrow: the daily pre-warm job + detects `model: "timeout-stub"` and overwrites). The test was + updated to assert the new contract; if a future wave wants + strict "no persist on timeout" semantics back, this test pin + makes the regression visible. + +3. **Helper is best-effort.** The `try/catch` around + `auditLog.create` is intentional and preserved from the v1.4.37 + bmi-status original: a failed write must not crash the response. + `updatedAt: null` on persist-failure is the signal. Worth + documenting in v1.4.41 ops notes — a sustained burst of "persist + failed" events would mean DB pressure, not a code bug, and would + degrade the route to the pre-v1.4.37 re-race-every-visit + behaviour silently. + +4. **No `toBerlinDayKey` extraction.** Each route still owns its + own `toBerlinDayKey` local — Simplifier-residual M2 deferred to + v1.4.42 per the wave brief. The helper takes `todayKey` as an + input so the extraction is a follow-up refactor inside a single + file (`src/lib/utils/berlin-day-key.ts` or similar) and won't + touch this helper's interface. + +## Counts at-a-glance + +- 1 helper file added. +- 7 routes share one persist path (was 0; bmi was the only persist + before, the other 6 had bare-fallback returns). +- ~120 LOC of duplicate `auditLog.create` calls collapsed into the + helper. +- Tests: 144 → 155 (+11). +- LOC delta: +673 / -81 across 14 files (tests dominate; production + code delta is roughly neutral after the bmi inline-to-helper + collapse).