chore(release): v1.28.21 — sleep history heals itself; plateau context; sync diagnostics

A one-time background pass re-reads each connected account's Google Health
sleep history so nights stored twice before the sleep fix collapse to their
true total (new sleep_repaired_at marker, migration 0238; watermark-safe,
enqueued once at boot per un-repaired connection).

The sleep night read reports when two writers disagree about the same night —
the served total is unchanged, the disagreement rides along as an annotation
(sourceDiscrepancy on the night DTO) so clients can mark the number instead of
silently picking a side.

A GLP-1 medication whose weight has plateaued on the current dose says so next
to the estimated drug level (efficacy tab + insights) — a factual note from the
existing detector, association only, verb-guard covered.

Google Health diagnostics: the sync log now separates a daily-totals read that
returned nothing from one the importer could not parse
(googleHealth.rollup.emptyResponse vs droppedAll), and the connection test's
structure probe reports the raw response envelope key names when a rollup type
parses to zero — a per-account naming drift becomes visible from one report.
This commit is contained in:
Marc-André Bombeck committed 2026-07-10 21:23:00 +02:00
1 parent 49be6851ec
commit 1212ed91d5
34 files changed
+1256 -7

No files matched your search

@@ -244,6 +244,11 @@ const EXEMPT_ROUTES: ReadonlyArray<string> = [
// inventory / side-effect events), and medications is a core, always-on
// domain with no module gate. It is not an insights-module surface.
"src/app/api/insights/glp1-timeline/route.ts",
// GLP-1 weight-plateau read backing the plateau note beside the drug-level
// curve (efficacy tab + /insights/medications) — the same MEDICATIONS-domain
// rationale as glp1-timeline above: a deterministic detector over weight +
// dose history, no AI narrative, medications is core/always-on.
"src/app/api/insights/glp1-plateau/route.ts",
];
const MODULE_GATE_NEEDLE = "requireModuleEnabled(";
@@ -88,6 +88,9 @@ const NOT_COACH_OWNED_ROUTES: ReadonlyArray<string> = [
// ability to dispose of stale recommendations.
"src/app/api/insights/feedback/route.ts",
"src/app/api/insights/glp1-timeline/route.ts",
// Deterministic GLP-1 plateau detector read (no assistant prose) — same
// medications-domain posture as glp1-timeline directly above.
"src/app/api/insights/glp1-plateau/route.ts",
// v1.5.5 — per-user tile layout for the `/insights` surface. The
// endpoint persists tile visibility + ordering only; it carries no
// assistant prose and is the mirror of `/api/dashboard/widgets`,
@@ -0,0 +1,37 @@
/**
* v1.28.21 — GLP-1 weight-plateau read endpoint.
*
* Surfaces the existing server-side plateau detector
* (`detectGlp1Plateau`, v1.4.25) to the UI: until now the context only
* fed the insight-generation prompt. The two GLP-1 curve surfaces (the
* medication detail "Wirkung" tab and /insights/medications) render a
* compact association-only note from this read. `plateau` is `null`
* whenever the detector bows out (no active GLP-1 medication, < 21 days
* on the current dose, weight still dropping, or fewer than two
* readings), and the note hides cleanly. Mirrors the sibling
* `/api/insights/glp1-timeline` read: per-user, cheap, no module gate
* beyond auth. Auth via cookie or Bearer.
*/
import { apiHandler, requireAuth } from "@/lib/api-handler";
import { apiSuccess } from "@/lib/api-response";
import { annotate } from "@/lib/logging/context";
import {
detectGlp1Plateau,
PLATEAU_WINDOW_DAYS,
} from "@/lib/insights/glp1-plateau";
export const dynamic = "force-dynamic";
export const GET = apiHandler(async () => {
const { user } = await requireAuth();
const plateau = await detectGlp1Plateau(user.id);
annotate({
action: { name: "insights.glp1-plateau.read" },
meta: { detected: plateau !== null },
});
return apiSuccess({ plateau, windowDays: PLATEAU_WINDOW_DAYS });
});
@@ -115,6 +115,7 @@ async function runStructureProbe(
try {
let points: Record<string, unknown>[];
let requestShape: string | undefined;
let envelopeKeys: string[] | undefined;
if (dataType.timeField === "rollup") {
// One minimal dailyRollUp exercise per rollup type (7-day range) — the
// probe reports the response skeleton AND which documented request
@@ -130,6 +131,13 @@ async function runStructureProbe(
onShape: (shape) => {
requestShape = shape;
},
// Raw envelope key names of the first page (names only). When the
// parse yields zero points this is the one signal that separates
// "the service returned nothing" from "the service returned points
// under a key this reader does not know" — per-cohort naming drift.
onEnvelopeKeys: (keys) => {
envelopeKeys = keys;
},
},
);
} else {
@@ -155,6 +163,9 @@ async function runStructureProbe(
count: points.length,
structure: points.length > 0 ? describeStructure(points[0]) : null,
...(requestShape ? { requestShape } : {}),
// Only meaningful when the parse came back empty — a populated parse
// proves the envelope key already matches.
...(points.length === 0 && envelopeKeys ? { envelopeKeys } : {}),
};
} catch (e) {
results[name] =
+13
View File
@@ -88,6 +88,19 @@ function serializeSession(s: SleepSession) {
end: seg.end.toISOString(),
minutes: Math.round(seg.minutes),
})),
// Additive, observational: two writer buckets reported clearly
// different asleep totals for this session. Never changes the served
// totals above — the UI only marks the number with a discreet hint.
sourceDiscrepancy: s.sourceDiscrepancy
? {
deltaMinutes: Math.round(s.sourceDiscrepancy.deltaMinutes),
sources: s.sourceDiscrepancy.sources.map((b) => ({
source: b.source,
deviceType: b.deviceType,
asleepMinutes: Math.round(b.asleepMinutes),
})),
}
: null,
};
}
@@ -164,3 +164,29 @@ describe("<SleepHypnogram> — timeline bar visibility", () => {
expect(html).toContain('data-slot="sleep-hypnogram-breakdown"');
});
});
describe("<SleepHypnogram> — source discrepancy marker", () => {
const discrepancy = {
deltaMinutes: 160,
sources: [
{ source: "WITHINGS", deviceType: null, asleepMinutes: 615 },
{ source: "GOOGLE_HEALTH", deviceType: null, asleepMinutes: 455 },
],
};
it("renders the discreet marker when the server flags disagreeing sources", () => {
const html = render({ ...baseSession, sourceDiscrepancy: discrepancy });
expect(html).toContain('data-slot="sleep-source-discrepancy"');
// Muted marker, no colour wash — the trigger stays on the muted tier.
expect(html).toContain("Sources disagree");
});
it("omits the marker when the night carries no discrepancy", () => {
expect(render(baseSession)).not.toContain(
'data-slot="sleep-source-discrepancy"',
);
expect(render({ ...baseSession, sourceDiscrepancy: null })).not.toContain(
'data-slot="sleep-source-discrepancy"',
);
});
});
@@ -0,0 +1,76 @@
"use client";
/**
* v1.28.21 — compact GLP-1 weight-plateau note.
*
* Renders the existing server-side plateau detection (`detectGlp1Plateau`,
* until now prompt-only) as a discreet card on both GLP-1 curve surfaces:
* the medication detail "Wirkung" tab (below the estimated
* active-substance curve) and /insights/medications (below the same curve
* block). Reads `GET /api/insights/glp1-plateau`; when the detector
* returns `null` (no active GLP-1 medication, < 21 days on the current
* dose, weight still dropping, or too few readings) the card renders
* nothing.
*
* Association only, matching the efficacy-tab posture: the copy is a
* title + one evidence line (Δ kg over the window, reading count, days on
* the current dose) — no verdict, no advice, no dose suggestion. The
* strings live under `medications.efficacy.plateau.*` so the banned-verb
* guard (`medications-efficacy-verb-guard.test.ts`) covers them
* structurally.
*/
import { Scale } from "lucide-react";
import { useQuery } from "@tanstack/react-query";
import { Card, CardContent, CardHeader } from "@/components/ui/card";
import { TileHeader } from "@/components/insights/tile-header";
import { queryKeys } from "@/lib/query-keys";
import { apiGet } from "@/lib/api/api-fetch";
import { useTranslations } from "@/lib/i18n/context";
import type { Glp1PlateauContext } from "@/lib/insights/glp1-plateau";
interface Glp1PlateauResponse {
plateau: Glp1PlateauContext | null;
windowDays: number;
}
export function Glp1PlateauNote() {
const { t } = useTranslations();
const { data } = useQuery({
queryKey: queryKeys.insightsGlp1Plateau(),
queryFn: () => apiGet<Glp1PlateauResponse>("/api/insights/glp1-plateau"),
staleTime: 60_000,
});
if (!data?.plateau) return null;
const plateau = data.plateau;
const delta =
plateau.weightDeltaKg > 0
? `+${plateau.weightDeltaKg}`
: `${plateau.weightDeltaKg}`;
const dose = `${plateau.drug} ${plateau.doseValue} ${plateau.doseUnit}`;
return (
<Card className="gap-2 py-3 md:py-4" data-slot="glp1-plateau-note">
<CardHeader>
<TileHeader
size="sm"
icon={Scale}
title={t("medications.efficacy.plateau.title")}
/>
</CardHeader>
<CardContent>
<p className="text-muted-foreground text-sm">
{t("medications.efficacy.plateau.evidence", {
delta,
window: data.windowDays,
readings: plateau.readingsCount,
days: plateau.daysOnDose,
dose,
})}
</p>
</CardContent>
</Card>
);
}
@@ -22,6 +22,7 @@ import dynamic from "next/dynamic";
import { useQuery } from "@tanstack/react-query";
import { ChartSkeleton } from "@/components/charts/chart-skeleton";
import { Glp1PlateauNote } from "@/components/insights/glp1-plateau-note";
import { queryKeys } from "@/lib/query-keys";
import { apiGet } from "@/lib/api/api-fetch";
@@ -80,6 +81,10 @@ export function Glp1SubstanceCurveSummary({
/>
</div>
))}
{/* v1.28.21 — weight-plateau note (association only), below the
curve(s). Self-gating: renders nothing unless the server-side
detector reports a plateau on the current dose. */}
<Glp1PlateauNote />
</div>
);
}
+119 -1
View File
@@ -10,7 +10,15 @@ import {
YAxis,
} from "recharts";
import { TriangleAlert } from "lucide-react";
import { Card, CardContent, CardHeader } from "@/components/ui/card";
import {
Tooltip,
TooltipContent,
TooltipProvider,
TooltipTrigger,
} from "@/components/ui/tooltip";
import { TileHeader } from "@/components/insights/tile-header";
import { useTranslations, useTimeFormatPreference } from "@/lib/i18n/context";
import { hourCycleOptions } from "@/lib/format-locale";
@@ -71,6 +79,20 @@ export interface SleepHypnogramSession {
* Withings, Fitbit) is `false` and keeps the timeline.
*/
reconstructed?: boolean;
/**
* Non-null when two writer buckets reported clearly different asleep
* totals for this night (server-computed, observational only — the
* headline total stays the winning writer's). Renders as a discreet
* marker with a per-source breakdown in a tooltip.
*/
sourceDiscrepancy?: {
deltaMinutes: number;
sources: {
source: string;
deviceType: string | null;
asleepMinutes: number;
}[];
} | null;
}
export interface SleepHypnogramProps {
@@ -112,6 +134,61 @@ function formatMinutes(total: number, locale: string): string {
return hours > 0 ? `${hours}h ${mins}m` : `${mins}m`;
}
/**
* Localised label keys per `MeasurementSource` — the same map the
* source-priority settings surface uses (`sources-section.tsx`), so both
* surfaces humanise a source identically.
*/
const SOURCE_LABEL_KEYS: Record<string, string> = {
WITHINGS: "settings.sections.sources.sourceLabels.WITHINGS",
APPLE_HEALTH: "settings.sections.sources.sourceLabels.APPLE_HEALTH",
MANUAL: "settings.sections.sources.sourceLabels.MANUAL",
IMPORT: "settings.sections.sources.sourceLabels.IMPORT",
WHOOP: "settings.sections.sources.sourceLabels.WHOOP",
COMPUTED: "settings.sections.sources.sourceLabels.COMPUTED",
FITBIT: "settings.sections.sources.sourceLabels.FITBIT",
};
/**
* Brand names for sources without a localised settings label — brand
* spellings are locale-invariant, so no i18n key is needed for them.
*/
const SOURCE_BRAND_NAMES: Record<string, string> = {
OURA: "Oura",
POLAR: "Polar",
GOOGLE_HEALTH: "Google Health",
NIGHTSCOUT: "Nightscout",
STRAVA: "Strava",
TELEGRAM: "Telegram",
MCP: "MCP",
};
/**
* Localised device-type label keys (`Measurement.deviceType`), reused from
* the source-priority settings surface. Appended in parentheses so two
* writer apps behind the same source (watch vs phone under Apple Health)
* stay distinguishable in the discrepancy tooltip.
*/
const DEVICE_TYPE_LABEL_KEYS: Record<string, string> = {
watch: "settings.sections.sources.deviceLabels.watch",
band: "settings.sections.sources.deviceLabels.band",
ring: "settings.sections.sources.deviceLabels.ring",
phone: "settings.sections.sources.deviceLabels.phone",
scale: "settings.sections.sources.deviceLabels.scale",
other: "settings.sections.sources.deviceLabels.other",
};
function sourceDisplayName(
source: string,
deviceType: string | null,
t: (key: string) => string,
): string {
const labelKey = SOURCE_LABEL_KEYS[source];
const base = labelKey ? t(labelKey) : (SOURCE_BRAND_NAMES[source] ?? source);
const deviceKey = deviceType ? DEVICE_TYPE_LABEL_KEYS[deviceType] : undefined;
return deviceKey ? `${base} (${t(deviceKey)})` : base;
}
export function SleepHypnogram({ session }: SleepHypnogramProps) {
const { t, locale } = useTranslations();
const timeFormat = useTimeFormatPreference();
@@ -251,10 +328,51 @@ export function SleepHypnogram({ session }: SleepHypnogramProps) {
<CardHeader>
<div className="flex flex-col gap-0.5">
<TileHeader title={t("insights.sleep.hypnogram.title")} />
<span className="text-muted-foreground text-xs">
<span className="text-muted-foreground flex items-center gap-1 text-xs">
{t("insights.sleep.hypnogram.subtitle", {
asleep: formatMinutes(session.asleepMinutes, locale),
})}
{/* Discreet source-discrepancy marker: two writers reported
clearly different totals for this night. Observational — the
headline stays the winning writer's number; the tooltip lists
each source's own total. Muted, no colour wash, no banner;
negative margins keep the 44 px hit target from growing the
caption line (same trick as measurement-diversity-nudge). */}
{session.sourceDiscrepancy ? (
<TooltipProvider delayDuration={150}>
<Tooltip>
<TooltipTrigger asChild>
<button
type="button"
data-slot="sleep-source-discrepancy"
aria-label={t(
"insights.sleep.sourceDiscrepancy.tooltipTitle",
)}
className="text-muted-foreground focus-visible:ring-ring/50 -mx-3 -my-3 inline-flex min-h-11 min-w-11 shrink-0 items-center justify-center rounded-full focus-visible:ring-2 focus-visible:outline-none"
>
<TriangleAlert className="size-3.5" aria-hidden="true" />
</button>
</TooltipTrigger>
<TooltipContent
data-slot="sleep-source-discrepancy-body"
align="start"
className="max-w-xs leading-relaxed"
>
<p className="font-medium">
{t("insights.sleep.sourceDiscrepancy.tooltipTitle")}
</p>
<p>
{session.sourceDiscrepancy.sources
.map(
(b) =>
`${sourceDisplayName(b.source, b.deviceType, t)} ${formatMinutes(b.asleepMinutes, locale)}`,
)
.join(" · ")}
</p>
</TooltipContent>
</Tooltip>
</TooltipProvider>
) : null}
</span>
{/* The night's measuring source rides the header as a muted
caption — it is already on the wire, and "which device
@@ -16,6 +16,7 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";
import { MedicationDetailSection } from "@/components/medications/medication-detail-section";
import { TileHeader } from "@/components/insights/tile-header";
import { Glp1PlateauNote } from "@/components/insights/glp1-plateau-note";
import { Card, CardContent, CardHeader } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
import {
@@ -170,7 +171,7 @@ export function EfficacyTab({
straight into the tab's `space-y-6` rhythm. Additive: no existing
Wirkung content changes. */}
{isGlp1 && medicationName != null && medicationDose != null ? (
<div data-slot="wirkung-drug-level-section">
<div className="space-y-6" data-slot="wirkung-drug-level-section">
<DrugLevelChart
medication={{
id: medicationId,
@@ -178,6 +179,10 @@ export function EfficacyTab({
dose: medicationDose,
}}
/>
{/* v1.28.21 — weight-plateau note (association only). Self-gating:
renders nothing unless the server-side detector reports a
plateau on the current dose. */}
<Glp1PlateauNote />
</div>
) : null}
@@ -1037,3 +1037,154 @@ describe("per-night writer richness pick", () => {
expect(after[0].asleepMinutes).toBe(410);
});
});
describe("source discrepancy annotation", () => {
// Granular Apple night (300 + 90 + 65 = 455 asleep minutes) next to a
// bare Withings aggregate claiming 615 for the same session. Apple wins
// the night on granular richness; Withings' disagreement is observed
// only, never blended into the served total.
const discrepantRows: SleepStageRow[] = [
srcRow("2026-06-04T00:30:00.000Z", "CORE", 300, "APPLE_HEALTH"),
srcRow("2026-06-04T03:00:00.000Z", "DEEP", 90, "APPLE_HEALTH"),
srcRow("2026-06-04T05:00:00.000Z", "REM", 65, "APPLE_HEALTH"),
srcRow("2026-06-04T05:30:00.000Z", "ASLEEP", 615, "WITHINGS"),
];
it("flags two writer buckets whose asleep totals clearly disagree", () => {
const sessions = reconstructSleepSessions(discrepantRows, "UTC");
expect(sessions).toHaveLength(1);
const s = sessions[0];
expect(s.sourceDiscrepancy).toEqual({
deltaMinutes: 160,
sources: [
{ source: "WITHINGS", deviceType: null, asleepMinutes: 615 },
{ source: "APPLE_HEALTH", deviceType: null, asleepMinutes: 455 },
],
});
});
it("never changes the served total — the winning writer's number stands", () => {
// The flagged night serves the SAME asleep total as the identical night
// without the disagreeing second writer: the annotation observes, the
// writer collapse decides.
const flagged = reconstructSleepSessions(discrepantRows, "UTC");
const winnerOnly = reconstructSleepSessions(
discrepantRows.filter((r) => r.source === "APPLE_HEALTH"),
"UTC",
);
expect(flagged[0].source).toBe("APPLE_HEALTH");
expect(flagged[0].asleepMinutes).toBe(455);
expect(flagged[0].asleepMinutes).toBe(winnerOnly[0].asleepMinutes);
expect(winnerOnly[0].sourceDiscrepancy).toBeNull();
});
it("stays null when the buckets agree within the absolute threshold", () => {
// 480 vs 455 → delta 25 ≤ 45 min: ordinary sensor variance, no flag.
const rows: SleepStageRow[] = [
srcRow("2026-06-04T00:30:00.000Z", "CORE", 300, "APPLE_HEALTH"),
srcRow("2026-06-04T03:00:00.000Z", "DEEP", 90, "APPLE_HEALTH"),
srcRow("2026-06-04T05:00:00.000Z", "REM", 65, "APPLE_HEALTH"),
srcRow("2026-06-04T05:30:00.000Z", "ASLEEP", 480, "WITHINGS"),
];
const sessions = reconstructSleepSessions(rows, "UTC");
expect(sessions).toHaveLength(1);
expect(sessions[0].sourceDiscrepancy).toBeNull();
});
it("stays null when the delta clears the floor but not the relative gate", () => {
// 555 vs 500 → delta 55 > 45 min but ≤ 20% of 555 (111): a one-hour
// spread on a long night is not a clear disagreement.
const rows: SleepStageRow[] = [
srcRow("2026-06-04T00:30:00.000Z", "CORE", 345, "APPLE_HEALTH"),
srcRow("2026-06-04T03:00:00.000Z", "DEEP", 90, "APPLE_HEALTH"),
srcRow("2026-06-04T05:00:00.000Z", "REM", 65, "APPLE_HEALTH"),
srcRow("2026-06-04T05:30:00.000Z", "ASLEEP", 555, "WITHINGS"),
];
const sessions = reconstructSleepSessions(rows, "UTC");
expect(sessions).toHaveLength(1);
expect(sessions[0].asleepMinutes).toBe(500);
expect(sessions[0].sourceDiscrepancy).toBeNull();
});
it("stays null for a single-writer session", () => {
const rows: SleepStageRow[] = [
srcRow("2026-06-04T00:30:00.000Z", "CORE", 300, "APPLE_HEALTH"),
srcRow("2026-06-04T03:00:00.000Z", "DEEP", 90, "APPLE_HEALTH"),
];
const sessions = reconstructSleepSessions(rows, "UTC");
expect(sessions).toHaveLength(1);
expect(sessions[0].sourceDiscrepancy).toBeNull();
});
it("an IN_BED/AWAKE-only writer makes no asleep claim and never flags", () => {
// The classic watch + phone pairing: the phone writes only the in-bed
// envelope. It carries no asleep total, so there is nothing to disagree
// about — the marker must not fire on every dual-writer Apple night.
const rows: SleepStageRow[] = [
writerRow(
"2026-06-04T00:30:00.000Z",
"CORE",
300,
"APPLE_HEALTH",
"watch",
),
writerRow(
"2026-06-04T03:00:00.000Z",
"DEEP",
90,
"APPLE_HEALTH",
"watch",
),
writerRow(
"2026-06-04T05:30:00.000Z",
"IN_BED",
480,
"APPLE_HEALTH",
"phone",
),
];
const sessions = reconstructSleepSessions(rows, "UTC");
expect(sessions).toHaveLength(1);
expect(sessions[0].sourceDiscrepancy).toBeNull();
});
it("distinguishes two writers behind one source by device type", () => {
// Watch granular vs phone coarse ASLEEP behind the same APPLE_HEALTH
// source: the writer-bucket key (source, deviceType) keeps them apart,
// and the annotation carries the device type so the UI can label both.
const rows: SleepStageRow[] = [
writerRow(
"2026-06-04T00:30:00.000Z",
"CORE",
300,
"APPLE_HEALTH",
"watch",
),
writerRow(
"2026-06-04T03:00:00.000Z",
"DEEP",
90,
"APPLE_HEALTH",
"watch",
),
writerRow("2026-06-04T05:00:00.000Z", "REM", 65, "APPLE_HEALTH", "watch"),
writerRow(
"2026-06-04T05:30:00.000Z",
"ASLEEP",
615,
"APPLE_HEALTH",
"phone",
),
];
const sessions = reconstructSleepSessions(rows, "UTC");
expect(sessions).toHaveLength(1);
expect(sessions[0].asleepMinutes).toBe(455);
expect(sessions[0].sourceDiscrepancy).toEqual({
deltaMinutes: 160,
sources: [
{ source: "APPLE_HEALTH", deviceType: "phone", asleepMinutes: 615 },
{ source: "APPLE_HEALTH", deviceType: "watch", asleepMinutes: 455 },
],
});
});
});
+86
View File
@@ -323,6 +323,80 @@ function sourceOfWriterKey(key: string): string {
return i === -1 ? key : key.slice(0, i);
}
/**
* Thresholds for the per-session source-discrepancy annotation. Two writer
* buckets "clearly disagree" on a night only when the spread of their asleep
* totals exceeds BOTH gates — an absolute floor (small deltas are ordinary
* sensor variance) and a relative one (a 50-minute delta matters on a
* 2-hour nap, not on a 10-hour night).
*/
const DISCREPANCY_MIN_DELTA_MINUTES = 45;
const DISCREPANCY_MIN_RATIO = 0.2;
/**
* OBSERVATIONAL annotation: two writer buckets reported clearly different
* asleep totals for the same session. Purely additive — it never changes
* which writer wins the night or what total is served; it only surfaces
* that a non-winning bucket disagreed, so the UI can show a discreet
* "sources disagree" marker where the number renders.
*/
export interface SleepSourceDiscrepancy {
/** max − min asleep minutes across the disagreeing writer buckets. */
deltaMinutes: number;
/** Every writer bucket with an asleep total, most asleep minutes first. */
sources: {
source: string;
deviceType: string | null;
asleepMinutes: number;
}[];
}
/**
* Compare the per-writer asleep totals of ONE session and flag a clear
* disagreement. Buckets follow the same `(source, deviceType)` writer key
* the dedup collapse uses, and each bucket's total applies the same
* granular-over-bare rule as the served number, so the comparison is
* apples-to-apples. Source-less legacy rows are skipped (a bucket the UI
* cannot label is not a nameable second opinion), as are buckets with no
* asleep minutes at all (an IN_BED/AWAKE-only phone writer makes no claim
* about the asleep total). Returns null when fewer than two buckets carry
* an asleep total or the spread stays inside the thresholds.
*/
function sessionSourceDiscrepancy(
rows: readonly SleepStageRow[],
): SleepSourceDiscrepancy | null {
const rowsByWriter = new Map<string, SleepStageRow[]>();
for (const r of rows) {
if (r.source == null) continue;
const key = writerKeyOf(r);
const list = rowsByWriter.get(key) ?? [];
list.push(r);
rowsByWriter.set(key, list);
}
if (rowsByWriter.size < 2) return null;
const buckets: SleepSourceDiscrepancy["sources"] = [];
for (const [key, writerRows] of rowsByWriter) {
const asleepMinutes = asleepMinutesOf(writerRows);
if (asleepMinutes <= 0) continue;
buckets.push({
source: sourceOfWriterKey(key),
deviceType: writerRows[0].deviceType ?? null,
asleepMinutes,
});
}
if (buckets.length < 2) return null;
buckets.sort(
(a, b) =>
b.asleepMinutes - a.asleepMinutes || (a.source < b.source ? -1 : 1),
);
const max = buckets[0].asleepMinutes;
const min = buckets[buckets.length - 1].asleepMinutes;
const delta = max - min;
if (delta <= DISCREPANCY_MIN_DELTA_MINUTES) return null;
if (delta <= max * DISCREPANCY_MIN_RATIO) return null;
return { deltaMinutes: delta, sources: buckets };
}
/**
* Count of DISTINCT granular stages (CORE / DEEP / REM) in a row set — the
* stage-richness score of a writer's night. 3 = full hypnogram, 0 = coarse
@@ -641,6 +715,14 @@ export interface SleepSession {
* Fitbit) stay `false`.
*/
reconstructed: boolean;
/**
* Non-null when two writer buckets reported clearly different asleep
* totals for this session (see `sessionSourceDiscrepancy`). Observational
* only — the served `asleepMinutes` stays the winning writer's total; the
* annotation lets the UI mark the number with a discreet
* "sources disagree" hint.
*/
sourceDiscrepancy: SleepSourceDiscrepancy | null;
}
/** Resolve a stage row to its absolute span (start = end − duration). */
@@ -791,6 +873,10 @@ export function reconstructSleepSessions(
// approximate layout; a real-series source (Apple/Withings/Fitbit) is
// measured.
reconstructed: RECONSTRUCTED_TIMELINE_SOURCES.has(canonicalSource),
// Compared across the RAW session (every writer, pre-collapse) so a
// losing bucket's disagreement is visible; the served totals above
// stay winner-only.
sourceDiscrepancy: sessionSourceDiscrepancy(session),
});
}
return sessions.sort((a, b) => a.start.getTime() - b.start.getTime());
+20
View File
@@ -1025,6 +1025,16 @@ interface RollupQuery {
* reports which shape Google actually accepted.
*/
onShape?: (shape: GoogleHealthRollupShape) => void;
/**
* Observes the raw top-level KEY NAMES of the first response page (never
* values). A rollup read that parses zero points is ambiguous — the service
* either returned nothing (account-side materialisation) or returned points
* under an envelope key this reader does not know (a per-cohort naming
* drift, the class of mismatch this integration has hit three times). The
* structure probe surfaces these keys so a live account settles it in one
* report: `["rollupDataPoints"]` = genuinely empty, anything else = drift.
*/
onEnvelopeKeys?: (keys: string[]) => void;
}
/** The dailyRollUp request shape a walk settled on. */
@@ -1152,6 +1162,16 @@ export async function fetchDailyRollUp(
});
}
// Surface the raw envelope key names of the very first page (names
// only, never values) — see `RollupQuery.onEnvelopeKeys`.
if (
chunkIndex === 0 &&
pageCount === 0 &&
json &&
typeof json === "object"
) {
query.onEnvelopeKeys?.(Object.keys(json));
}
for (const p of json?.rollupDataPoints ?? []) points.push(p);
pageToken = json?.nextPageToken ?? null;
pageCount += 1;
+22
View File
@@ -105,6 +105,15 @@ export async function syncUserActivity(
const start = opts.start;
let imported = 0;
// Rollup observability — a cumulative type that "works" (HTTP 200) can still
// land zero rows for two very different reasons, and the sync log must tell
// them apart without a live-account debugging round-trip:
// emptyResponse → the service returned NO rollup points at all (Google-side
// materialisation for the account / device cohort);
// droppedAll → points arrived but none survived the mapper (a response
// naming/shape drift on this account's service revision).
const rollupEmptyResponse: string[] = [];
const rollupDroppedAll: string[] = [];
for (const resource of ROLLUP_RESOURCES) {
let points: Record<string, unknown>[];
try {
@@ -131,12 +140,25 @@ export async function syncUserActivity(
});
}
}
if (points.length === 0) {
rollupEmptyResponse.push(resource.verb);
} else if (readings.length === 0) {
rollupDroppedAll.push(resource.verb);
}
imported += (
await upsertGoogleHealthMeasurements(userId, readings, {
deferRollup: opts.deferRollup,
})
).imported;
}
if (rollupEmptyResponse.length > 0 || rollupDroppedAll.length > 0) {
annotate({
meta: {
"googleHealth.rollup.emptyResponse": rollupEmptyResponse,
"googleHealth.rollup.droppedAll": rollupDroppedAll,
},
});
}
// VO2 max — a daily summary (list + `.date` filter), not a rollup type.
try {
+6 -1
View File
@@ -20,7 +20,12 @@ import { prisma } from "@/lib/db";
import type { Locale } from "@/lib/i18n/config";
import { sanitizeForPrompt } from "@/lib/insights/sanitize";
const PLATEAU_WINDOW_DAYS = 21;
/**
* Trailing window (days) the detector compares weight across. Exported
* so the read endpoint (`GET /api/insights/glp1-plateau`) can surface
* the window alongside the context without duplicating the constant.
*/
export const PLATEAU_WINDOW_DAYS = 21;
const PLATEAU_THRESHOLD_KG = 0.5;
export interface Glp1PlateauContext {
@@ -0,0 +1,142 @@
/**
* v1.28.x — Google Health one-shot sleep duplicate-repair self-convergence
* tests (mocked).
* - discovery only matches connections not yet repaired
* (`sleepRepairedAt IS NULL`) and singleton-keys the enqueue per user;
* - a completed pass runs a FULL sleep re-read (no `start` lower bound),
* stamps `sleepRepairedAt` so the next discovery drops the account, and
* NEVER touches the `lastSyncedAt` sync watermark;
* - the discovery is best-effort — errors surface through the result value.
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
const { prismaMock, bossSend, syncUserSleep } = vi.hoisted(() => ({
prismaMock: {
googleHealthConnection: { findMany: vi.fn(), update: vi.fn() },
},
bossSend: vi.fn(),
syncUserSleep: vi.fn(),
}));
vi.mock("@/lib/db", () => ({ prisma: prismaMock }));
vi.mock("@/lib/jobs/boss-instance", () => ({
getGlobalBoss: () => ({ send: bossSend }),
}));
vi.mock("@/lib/google-health/sync-sleep", () => ({
syncUserSleep: (...a: unknown[]) => syncUserSleep(...a),
}));
vi.mock("@/lib/logging/context", () => ({
annotate: () => {},
getEvent: () => null,
}));
import {
enqueueBootTimeGoogleHealthSleepRepair,
runGoogleHealthSleepRepairForUser,
} from "../google-health-sleep-repair";
beforeEach(() => {
vi.clearAllMocks();
});
describe("enqueueBootTimeGoogleHealthSleepRepair — discovery", () => {
it("queries only un-repaired connections and enqueues one singleton-keyed job per user", async () => {
prismaMock.googleHealthConnection.findMany.mockResolvedValue([
{ userId: "u1" },
{ userId: "u2" },
]);
bossSend.mockResolvedValue("job-id");
const result = await enqueueBootTimeGoogleHealthSleepRepair();
expect(prismaMock.googleHealthConnection.findMany).toHaveBeenCalledWith(
expect.objectContaining({ where: { sleepRepairedAt: null } }),
);
expect(result.enqueued).toBe(2);
expect(bossSend).toHaveBeenCalledWith(
"google-health-sleep-repair",
expect.objectContaining({ userId: "u1" }),
expect.objectContaining({
singletonKey: "google-health-sleep-repair|u1",
}),
);
expect(bossSend).toHaveBeenCalledWith(
"google-health-sleep-repair",
expect.objectContaining({ userId: "u2" }),
expect.objectContaining({
singletonKey: "google-health-sleep-repair|u2",
}),
);
});
it("self-converges: no un-repaired connections → nothing enqueued", async () => {
prismaMock.googleHealthConnection.findMany.mockResolvedValue([]);
const result = await enqueueBootTimeGoogleHealthSleepRepair();
expect(result.enqueued).toBe(0);
expect(bossSend).not.toHaveBeenCalled();
});
it("never throws — surfaces a discovery error through the result value", async () => {
prismaMock.googleHealthConnection.findMany.mockRejectedValue(
new Error("db down"),
);
const result = await enqueueBootTimeGoogleHealthSleepRepair();
expect(result.error).toBe("db down");
expect(result.enqueued).toBe(0);
});
});
describe("runGoogleHealthSleepRepairForUser", () => {
it("runs a FULL sleep re-read (no start lower bound) and stamps sleepRepairedAt", async () => {
syncUserSleep.mockResolvedValue(42);
prismaMock.googleHealthConnection.update.mockResolvedValue({});
const { imported } = await runGoogleHealthSleepRepairForUser("u1");
expect(imported).toBe(42);
// Full-history walk: no `start` in the options object.
const syncOpts = syncUserSleep.mock.calls[0]![1] as Record<string, unknown>;
expect(syncUserSleep).toHaveBeenCalledWith("u1", expect.any(Object));
expect(syncOpts).not.toHaveProperty("start");
const updateArg = prismaMock.googleHealthConnection.update.mock
.calls[0]![0] as {
where: Record<string, unknown>;
data: Record<string, unknown>;
};
expect(updateArg.where).toEqual({ userId: "u1" });
expect(updateArg.data.sleepRepairedAt).toBeInstanceOf(Date);
});
it("does NOT touch the lastSyncedAt sync watermark", async () => {
syncUserSleep.mockResolvedValue(7);
prismaMock.googleHealthConnection.update.mockResolvedValue({});
await runGoogleHealthSleepRepairForUser("u1");
// The single connection write stamps ONLY the repair marker — the
// watermark stays where the incremental orchestrator left it.
for (const call of prismaMock.googleHealthConnection.update.mock.calls) {
const { data } = call[0] as { data: Record<string, unknown> };
expect(data).not.toHaveProperty("lastSyncedAt");
expect(Object.keys(data)).toEqual(["sleepRepairedAt"]);
}
expect(prismaMock.googleHealthConnection.update).toHaveBeenCalledTimes(1);
});
it("propagates a sync failure without stamping the marker (pg-boss retries)", async () => {
syncUserSleep.mockRejectedValue(new Error("google 500"));
await expect(runGoogleHealthSleepRepairForUser("u1")).rejects.toThrow(
"google 500",
);
expect(prismaMock.googleHealthConnection.update).not.toHaveBeenCalled();
});
});
+132
View File
@@ -0,0 +1,132 @@
/**
* v1.28.x — pg-boss queue + boot-time one-shot sleep duplicate repair for
* Google Health connections. Modelled on the self-converging backfill
* (`src/lib/jobs/google-health-backfill.ts`): a discovery query enqueues one
* job per connection not yet repaired, and the pass is idempotent across
* reboots (the predicate `sleep_repaired_at IS NULL` drops a connection once
* its repair finishes).
*
* Why: the pre-v1.28.18 volatile sleep externalId minted parallel duplicate
* rows every time Google re-scored a night, over-counting the night total.
* The fix (`replaceStaleGoogleHealthSleep`) makes any RE-READ night self-heal,
* and the incremental 24 h overlap heals recent nights — but historical nights
* keep their duplicates until re-read. This job forces one full sleep-history
* re-read per connection so the replace-by-window collapses every night once.
*
* Watermark-safe by construction: `syncUserSleep` never reads or stamps
* `lastSyncedAt` — `markSynced` is owned by the orchestrator
* (`syncUserGoogleHealth`), which this job does not call. Passing no `start`
* makes the resource fetch full-history (undefined = no lower bound).
*
* The queue name MUST be registered in `allQueues` in
* `src/lib/jobs/reminder/register-integration-sync.ts` or pg-boss never
* provisions it and the boot enqueue silently never drains (the v1.4.37
* dead-queue class).
*/
import { prisma } from "@/lib/db";
import { annotate } from "@/lib/logging/context";
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { syncUserSleep } from "@/lib/google-health/sync-sleep";
export const GOOGLE_HEALTH_SLEEP_REPAIR_QUEUE = "google-health-sleep-repair";
/**
* Serial concurrency — a repair walks the full sleep history for one account
* and is rate-bounded by Google's per-app quota; concurrency-1 keeps it from
* crowding the request pool, matching `GOOGLE_HEALTH_BACKFILL_CONCURRENCY`.
*/
export const GOOGLE_HEALTH_SLEEP_REPAIR_CONCURRENCY = 1;
export interface GoogleHealthSleepRepairPayload {
userId: string;
enqueuedAt: string;
}
/**
* Per-user repair handler. Runs a full sleep-history re-sync for one account —
* no `start`, so the fetch walks the whole history and
* `replaceStaleGoogleHealthSleep` collapses each night's duplicates in the
* write path — then stamps `sleepRepairedAt` so the discovery query drops it.
* Idempotent: the per-segment upserts are key-stable and the replace-by-window
* clears stale copies, so a re-run (e.g. a reboot mid-walk) converges rather
* than duplicating. Does NOT move `lastSyncedAt`.
*/
export async function runGoogleHealthSleepRepairForUser(
userId: string,
): Promise<{ imported: number }> {
const imported = await syncUserSleep(userId, { deferRollup: false });
await prisma.googleHealthConnection.update({
where: { userId },
data: { sleepRepairedAt: new Date() },
});
annotate({
action: {
name: "googleHealth.sleepRepair.complete",
details: { imported },
},
});
return { imported };
}
/**
* Boot-time discovery. Finds every Google Health connection not yet repaired
* (`sleep_repaired_at IS NULL`) and enqueues one repair job per account.
*
* Idempotent across reboots: once a connection's repair completes,
* `sleepRepairedAt` is set and the predicate drops it from the discovery set.
* pg-boss `singletonKey` coalesces duplicate sends so a fast restart while a
* job is queued doesn't double up.
*
* Best-effort: errors are returned through the result value so the worker boot
* never fails because of a repair miss.
*/
export async function enqueueBootTimeGoogleHealthSleepRepair(): Promise<{
enqueued: number;
skipped: number;
error: string | null;
}> {
const boss = getGlobalBoss();
if (!boss) {
return { enqueued: 0, skipped: 0, error: null };
}
try {
const connections = await prisma.googleHealthConnection.findMany({
where: { sleepRepairedAt: null },
select: { userId: true },
});
if (connections.length === 0) {
return { enqueued: 0, skipped: 0, error: null };
}
let enqueued = 0;
let skipped = 0;
for (const { userId } of connections) {
const payload: GoogleHealthSleepRepairPayload = {
userId,
enqueuedAt: new Date().toISOString(),
};
const jobId = await boss.send(GOOGLE_HEALTH_SLEEP_REPAIR_QUEUE, payload, {
retryLimit: 3,
retryDelay: 60,
retryBackoff: true,
singletonKey: `google-health-sleep-repair|${userId}`,
});
if (jobId) {
enqueued += 1;
} else {
skipped += 1;
}
}
return { enqueued, skipped, error: null };
} catch (err) {
return {
enqueued: 0,
skipped: 0,
error: err instanceof Error ? err.message : String(err),
};
}
}
@@ -35,6 +35,13 @@ import {
enqueueBootTimeGoogleHealthBackfill,
type GoogleHealthBackfillPayload,
} from "@/lib/jobs/google-health-backfill";
import {
GOOGLE_HEALTH_SLEEP_REPAIR_QUEUE,
GOOGLE_HEALTH_SLEEP_REPAIR_CONCURRENCY,
runGoogleHealthSleepRepairForUser,
enqueueBootTimeGoogleHealthSleepRepair,
type GoogleHealthSleepRepairPayload,
} from "@/lib/jobs/google-health-sleep-repair";
import {
STRAVA_BACKFILL_QUEUE,
STRAVA_BACKFILL_CONCURRENCY,
@@ -244,6 +251,10 @@ const allQueues = [
// self-converging boot backfill, and the daily OAuth-state ledger sweep.
GOOGLE_HEALTH_SYNC_QUEUE,
GOOGLE_HEALTH_BACKFILL_QUEUE,
// v1.28.x — one-shot sleep duplicate repair. Discovery enqueues one full
// sleep re-read per connection not yet repaired; the replace-by-window write
// path collapses each night's duplicate rows. Idempotent across reboots.
GOOGLE_HEALTH_SLEEP_REPAIR_QUEUE,
GOOGLE_HEALTH_OAUTH_STATE_CLEANUP_QUEUE,
// v1.17.1 — one-shot sleep-timeline backfill for WHOOP + Withings.
// Discovery enqueues one job per connection whose sleep rows predate the
@@ -429,6 +440,25 @@ export async function registerIntegrationSyncQueues(
}
},
);
// v1.28.x — one-shot Google Health sleep duplicate repair. The boot enqueue
// below sends one full sleep-history re-read per un-repaired connection; this
// handler runs it (watermark-safe — `syncUserSleep` never stamps
// `lastSyncedAt`) and stamps `sleepRepairedAt` so the discovery query drops
// the account.
await boss.work<GoogleHealthSleepRepairPayload>(
GOOGLE_HEALTH_SLEEP_REPAIR_QUEUE,
{ localConcurrency: GOOGLE_HEALTH_SLEEP_REPAIR_CONCURRENCY },
async (jobs) => {
for (const job of jobs) {
const { userId } = job.data;
const { imported } = await runGoogleHealthSleepRepairForUser(userId);
workerLog(
"info",
`[google-health-sleep-repair] user=${userId} imported=${imported}`,
);
}
},
);
await boss.work<GoogleHealthOAuthStateCleanupPayload>(
GOOGLE_HEALTH_OAUTH_STATE_CLEANUP_QUEUE,
{ localConcurrency: 1 },
@@ -600,6 +630,31 @@ export async function enqueueIntegrationSyncBootDiscovery(): Promise<void> {
);
}
// v1.28.x — one-shot Google Health sleep duplicate repair. Finds every
// connection not yet repaired and enqueues one full sleep re-read per
// account; a completed pass stamps `sleepRepairedAt`.
try {
const { enqueued, skipped, error } =
await enqueueBootTimeGoogleHealthSleepRepair();
if (error) {
workerLog(
"error",
`[google-health-sleep-repair] boot discovery failed: ${error}`,
);
} else {
workerLog(
"info",
`[google-health-sleep-repair] boot discovery: enqueued=${enqueued} skipped=${skipped}`,
);
}
} catch (err) {
workerLog(
"error",
"[google-health-sleep-repair] boot discovery threw an unexpected error",
err,
);
}
// v1.17.1 — one-shot sleep-timeline backfill. Finds every WHOOP + Withings
// connection whose sleep rows predate the stamp/shape fix and enqueues one
// job per (user, provider). A completed pass stamps `sleepTimelineBackfillAt`.
+23
View File
@@ -16,6 +16,7 @@ import {
derivedBatchQuery,
derivedBatchResponse,
correlationDiscoveryResponse,
glp1PlateauResponse,
insightStatusQuery,
insightStatusResponse,
medicationComplianceStatusResponse,
@@ -377,6 +378,28 @@ export const insightsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"/api/insights/glp1-plateau": {
get: {
tags: ["Insights"],
summary: "GLP-1 weight-plateau detection",
description:
"Deterministic (non-LLM) weight-plateau read for users on an active GLP-1 medication: flags a stable dose held for at least the trailing window with no weight loss beyond the threshold. `plateau` is null whenever the condition does not hold, so clients hide the note cleanly. Association only — no verdict, no dose advice. Auth via cookie or Bearer.",
responses: {
"200": {
description: "Plateau context (or null) plus the window length.",
content: {
"application/json": {
schema: dataEnvelope(
glp1PlateauResponse,
"InsightsGlp1PlateauResponseEnvelope",
),
},
},
},
...stdResponses,
},
},
},
"/api/insights/correlations": {
get: {
tags: ["Insights"],
@@ -418,6 +418,48 @@ export const correlationDiscoveryResponse = z
"v1.10.0 — FDR-controlled correlation discovery over a curated behaviour × outcome matrix, lagged behaviour → next-day outcome. Only statistically-defensible pairs surface; descriptive, never causal.",
});
// v1.28.21 — GLP-1 weight-plateau read. Mirrors the fields of the
// server-side detector context (`Glp1PlateauContext`); `plateau` is null
// whenever the detector bows out.
export const glp1PlateauResponse = z
.object({
plateau: z
.object({
drug: z.string().describe('Display drug name ("Mounjaro").'),
doseValue: z.number().describe("Current dose value (e.g. 7.5)."),
doseUnit: z.string().describe('Dose unit (e.g. "mg").'),
doseSince: z
.string()
.describe("ISO date (YYYY-MM-DD) the current dose started."),
daysOnDose: z
.number()
.int()
.describe("Days the user has been on the current dose."),
weightDeltaKg: z
.number()
.describe(
"Weight delta in kg over the trailing window (negative = loss).",
),
readingsCount: z
.number()
.int()
.describe("Number of weight readings considered."),
})
.nullable()
.describe(
"Null when no plateau is detected (no active GLP-1 medication, < window days on the current dose, weight still dropping, or fewer than two readings).",
),
windowDays: z
.number()
.int()
.describe("Trailing comparison window in days (currently 21)."),
})
.meta({
id: "InsightsGlp1PlateauResponse",
description:
"Deterministic weight-plateau detection for users on an active GLP-1 medication: stable dose for ≥ the window with no weight loss beyond the threshold. Association only — carries no verdict or advice.",
});
// The seven specialised `*-status` routes accept an optional locale
// override (the metric is fixed by the route path, unlike the generic
// metric-status route which carries it as a query field).
+23
View File
@@ -243,6 +243,29 @@ const sleepSessionResource = z.object({
),
stages: z.record(sleepStageEnum, z.number().int().nonnegative()),
segments: z.array(sleepSegmentResource),
sourceDiscrepancy: z
.object({
deltaMinutes: z
.number()
.int()
.nonnegative()
.describe(
"Spread (max − min) of the disagreeing per-writer asleep totals, in minutes.",
),
sources: z.array(
z.object({
source: z
.string()
.describe("MeasurementSource value of the writer bucket."),
deviceType: z.string().nullable(),
asleepMinutes: z.number().int().nonnegative(),
}),
),
})
.nullable()
.describe(
"Non-null when two writer buckets reported clearly different asleep totals for this session (> 45 min apart and > 20% of the larger total). Observational only — the served totals stay the winning writer's; clients may show a discreet 'sources disagree' hint listing each bucket's total.",
),
});
const sleepNightResponse = z
+6
View File
@@ -115,6 +115,12 @@ export const insightsKeys = {
insightsProviderChain: () => ["insights", "provider-chain"] as const,
insightsGlp1Timeline: (limit: number | string) =>
["insights", "glp1-timeline", limit] as const,
/**
* v1.28.21 — GLP-1 weight-plateau read (`/api/insights/glp1-plateau`).
* Per-user, no params; the `["insights"]` prefix keeps it inside the
* existing invalidation fan-out.
*/
insightsGlp1Plateau: () => ["insights", "glp1-plateau"] as const,
/**
* v1.5.5 — per-user insights tile layout (mirrors