Merge branch 'wave/v125-delight' into release/v1.25.0

src/lib/insights/__tests__/breathing-screening.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  summariseBreathing,
+  type BreathingRow,
+} from "@/lib/insights/breathing-screening";
+
+function night(daysAgo: number, value: number): BreathingRow {
+  return {
+    value,
+    measuredAt: new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000),
+  };
+}
+
+describe("summariseBreathing", () => {
+  it("is absent with no rows at all", () => {
+    const s = summariseBreathing([], []);
+    expect(s.present).toBe(false);
+    expect(s.nights).toBe(0);
+    expect(s.classification).toBeNull();
+    expect(s.trend).toBeNull();
+  });
+
+  it("classifies not-elevated with index nights and no events", () => {
+    const s = summariseBreathing([night(2, 3), night(1, 4)], []);
+    expect(s.present).toBe(true);
+    expect(s.nights).toBe(2);
+    expect(s.recentMeanIndex).toBe(3.5);
+    expect(s.classification).toBe("not-elevated");
+  });
+
+  it("classifies elevated when the device flagged events", () => {
+    const s = summariseBreathing([night(1, 5)], [night(1, 1)]);
+    expect(s.present).toBe(true);
+    expect(s.eventCount).toBe(1);
+    expect(s.classification).toBe("elevated");
+  });
+
+  it("computes an upward trend over enough nights", () => {
+    const rows = [
+      night(8, 2),
+      night(7, 2),
+      night(6, 2),
+      night(5, 8),
+      night(4, 8),
+      night(3, 8),
+      night(2, 8),
+      night(1, 8),
+    ];
+    const s = summariseBreathing(rows, []);
+    expect(s.trend).toBe("up");
+  });
+
+  it("leaves the trend null with too few nights", () => {
+    const s = summariseBreathing([night(2, 4), night(1, 5)], []);
+    expect(s.trend).toBeNull();
+  });
+});

src/lib/insights/__tests__/health-status.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+
+import { summariseHealthStatus } from "@/lib/insights/health-status";
+import type { VitalDeviation } from "@/lib/insights/derived/coincident-deviation";
+import type { ChangepointSignal } from "@/lib/insights/derived/changepoint";
+
+function vital(
+  outside: boolean,
+  direction: VitalDeviation["direction"],
+): VitalDeviation {
+  return {
+    type: "RESTING_HEART_RATE",
+    value: 70,
+    center: 60,
+    low: 55,
+    high: 65,
+    outside,
+    direction,
+  };
+}
+
+function shift(): ChangepointSignal {
+  return {
+    metric: "WEIGHT",
+    breakDate: "2026-06-10",
+    beforeMean: 80,
+    afterMean: 82,
+    direction: "up",
+    magnitude: 1.6,
+  };
+}
+
+describe("summariseHealthStatus", () => {
+  it("is absent when nothing is outside and no shift fired", () => {
+    const s = summariseHealthStatus([vital(false, "in")], []);
+    expect(s.present).toBe(false);
+    expect(s.deviations).toHaveLength(0);
+    expect(s.shifts).toHaveLength(0);
+  });
+
+  it("surfaces an out-of-band deviation", () => {
+    const s = summariseHealthStatus([vital(true, "above")], []);
+    expect(s.present).toBe(true);
+    expect(s.deviations).toHaveLength(1);
+    expect(s.deviations[0]).toMatchObject({
+      type: "RESTING_HEART_RATE",
+      direction: "above",
+    });
+  });
+
+  it("surfaces a changepoint shift even with no deviation", () => {
+    const s = summariseHealthStatus([vital(false, "in")], [shift()]);
+    expect(s.present).toBe(true);
+    expect(s.shifts).toHaveLength(1);
+    expect(s.shifts[0]).toMatchObject({ metric: "WEIGHT", direction: "up" });
+  });
+
+  it("drops a vital flagged outside but with an 'in' direction", () => {
+    const s = summariseHealthStatus([vital(true, "in")], []);
+    expect(s.present).toBe(false);
+  });
+});

src/lib/insights/__tests__/labs-changes.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  summariseLabChanges,
+  type LabChangeRow,
+} from "@/lib/insights/labs-changes";
+
+function row(
+  analyte: string,
+  value: number,
+  day: string,
+  opts: { unit?: string; low?: number | null; high?: number | null } = {},
+): LabChangeRow {
+  return {
+    analyte,
+    unit: opts.unit ?? "mg/dL",
+    value,
+    referenceLow: opts.low ?? null,
+    referenceHigh: opts.high ?? null,
+    takenAt: new Date(`${day}T08:00:00.000Z`),
+  };
+}
+
+describe("summariseLabChanges", () => {
+  it("is absent with no rows", () => {
+    expect(summariseLabChanges([])).toMatchObject({ present: false });
+  });
+
+  it("is absent with a single panel", () => {
+    const s = summariseLabChanges([row("LDL", 130, "2026-06-01")]);
+    expect(s.present).toBe(false);
+  });
+
+  it("is absent when no analyte is shared across panels", () => {
+    const s = summariseLabChanges([
+      row("LDL", 130, "2026-06-01"),
+      row("HbA1c", 5.4, "2026-05-01"),
+    ]);
+    expect(s.present).toBe(false);
+  });
+
+  it("pairs the two most-recent panels for a shared analyte", () => {
+    const s = summariseLabChanges([
+      row("LDL", 120, "2026-06-01", { high: 116 }),
+      row("LDL", 140, "2026-05-01"),
+      row("LDL", 150, "2026-04-01"),
+    ]);
+    expect(s.present).toBe(true);
+    expect(s.latestDate).toBe("2026-06-01");
+    expect(s.previousDate).toBe("2026-05-01");
+    expect(s.changes).toHaveLength(1);
+    const c = s.changes[0];
+    expect(c.latest).toBe(120);
+    expect(c.previous).toBe(140);
+    expect(c.delta).toBe(-20);
+    expect(c.direction).toBe("down");
+    expect(c.status).toBe("above");
+  });
+
+  it("skips qualitative (non-finite) values", () => {
+    const s = summariseLabChanges([
+      row("LDL", Number.NaN, "2026-06-01"),
+      row("LDL", 140, "2026-05-01"),
+    ]);
+    expect(s.present).toBe(false);
+  });
+});

src/lib/insights/breathing-screening.ts

@@ -0,0 +1,122 @@
+/**
+ * v1.25 — breathing-disturbance screening shaping.
+ *
+ * Reads the per-night sleep-breathing-disturbance index
+ * (`BREATHING_DISTURBANCES`, lower-better) and the device-flagged
+ * breathing-disturbance / possible-apnea events (`BREATHING_DISTURBANCE_EVENT`)
+ * a sync writes, and folds them into a calm awareness summary: how many nights
+ * are covered, the recent mean index, the short-window trend, and the device's
+ * own classification.
+ *
+ * This is a SCREENING SIGNAL ONLY — never a HealthLog diagnosis. The card built
+ * on top of this states that explicitly. The classification mirrors the device:
+ * a night the device flagged with one or more elevated-breathing events reads
+ * as "elevated"; with index nights and no flagged event it reads as
+ * "not-elevated". HealthLog invents no numeric threshold of its own.
+ *
+ * The math lives here, free of Prisma, so the present / absent / trend states
+ * are unit-testable in isolation.
+ */
+
+/** A single per-night reading (index) or a device-flagged event row. */
+export interface BreathingRow {
+  value: number;
+  measuredAt: Date;
+}
+
+export type BreathingTrend = "up" | "down" | "stable" | null;
+export type BreathingClassification = "not-elevated" | "elevated" | null;
+
+export interface BreathingScreeningSummary {
+  /** True when there is any index night or any flagged event to surface. */
+  present: boolean;
+  /** Number of nights with a per-night index reading. */
+  nights: number;
+  /** Mean of the index readings (lower-better), rounded to 1dp; null when none. */
+  recentMeanIndex: number | null;
+  /**
+   * Direction of the recent index vs the prior window. "up" is worse (more
+   * disturbance). Null when there are too few nights to compare.
+   */
+  trend: BreathingTrend;
+  /** Count of device-flagged breathing-disturbance / apnea events. */
+  eventCount: number;
+  /**
+   * The device's own classification: "elevated" when it flagged events,
+   * "not-elevated" when there are index nights and no flagged event, null when
+   * there is no data at all.
+   */
+  classification: BreathingClassification;
+}
+
+/** Window (most-recent nights) the trend compares against the prior block. */
+const TREND_WINDOW_NIGHTS = 7;
+/** Need at least this many nights total before a trend is meaningful. */
+const MIN_TREND_NIGHTS = 6;
+/** Relative band within which the recent mean reads as "stable". */
+const STABLE_BAND = 0.1;
+
+function mean(xs: readonly number[]): number {
+  if (xs.length === 0) return 0;
+  let sum = 0;
+  for (const x of xs) sum += x;
+  return sum / xs.length;
+}
+
+const round1 = (n: number): number => Math.round(n * 10) / 10;
+
+/**
+ * Summarise the breathing-screening signal. `indexRows` are the per-night
+ * index readings; `eventRows` are the device-flagged events. Order-independent
+ * — the helper sorts by `measuredAt` for the trend.
+ */
+export function summariseBreathing(
+  indexRows: readonly BreathingRow[],
+  eventRows: readonly BreathingRow[],
+): BreathingScreeningSummary {
+  const sorted = [...indexRows]
+    .filter((r) => Number.isFinite(r.value))
+    .sort((a, b) => a.measuredAt.getTime() - b.measuredAt.getTime());
+
+  const nights = sorted.length;
+  const eventCount = eventRows.length;
+
+  if (nights === 0 && eventCount === 0) {
+    return {
+      present: false,
+      nights: 0,
+      recentMeanIndex: null,
+      trend: null,
+      eventCount: 0,
+      classification: null,
+    };
+  }
+
+  const values = sorted.map((r) => r.value);
+  const recentMeanIndex = nights > 0 ? round1(mean(values)) : null;
+
+  let trend: BreathingTrend = null;
+  if (nights >= MIN_TREND_NIGHTS) {
+    const recent = values.slice(-TREND_WINDOW_NIGHTS);
+    const prior = values.slice(0, -TREND_WINDOW_NIGHTS);
+    if (recent.length > 0 && prior.length > 0) {
+      const recentMean = mean(recent);
+      const priorMean = mean(prior);
+      const band = Math.abs(priorMean) * STABLE_BAND;
+      const delta = recentMean - priorMean;
+      trend = Math.abs(delta) <= band ? "stable" : delta > 0 ? "up" : "down";
+    }
+  }
+
+  const classification: BreathingClassification =
+    eventCount > 0 ? "elevated" : nights > 0 ? "not-elevated" : null;
+
+  return {
+    present: true,
+    nights,
+    recentMeanIndex,
+    trend,
+    eventCount,
+    classification,
+  };
+}

src/lib/insights/health-status.ts

@@ -0,0 +1,84 @@
+/**
+ * v1.25 — health-status / baseline-drift shaping.
+ *
+ * Surfaces what is drifting from the user's own normal by combining two
+ * existing read-only engines:
+ *   - the personal-band deviations from the coincident-deviation flag
+ *     (`coincident-deviation.ts`, which fans `VITALS_BASELINE` across vitals),
+ *     keeping only the vitals that sit OUTSIDE their band today, and
+ *   - the dated, sustained level shifts from the changepoint detector
+ *     (`changepoint.ts`).
+ *
+ * This module owns only the pure reshaping — taking the engine outputs and
+ * folding them into the flat response the card reads — so the present / absent
+ * states are unit-testable without Prisma. It never labels a cause and never
+ * diagnoses; it lists what changed and frames it as awareness only.
+ */
+import type { MeasurementType } from "@/generated/prisma/client";
+import type { VitalDeviation } from "@/lib/insights/derived/coincident-deviation";
+import type { ChangepointSignal } from "@/lib/insights/derived/changepoint";
+
+/** One vital sitting outside its personal band today. */
+export interface HealthStatusDeviation {
+  type: MeasurementType;
+  /** Today's value. */
+  value: number;
+  /** Band center (median). */
+  center: number;
+  low: number;
+  high: number;
+  /** Which side of the band the value falls on. */
+  direction: "above" | "below";
+}
+
+/** One dated, sustained level shift from the changepoint detector. */
+export interface HealthStatusShift {
+  metric: MeasurementType;
+  /** YYYY-MM-DD of the first day of the new level. */
+  breakDate: string;
+  beforeMean: number;
+  afterMean: number;
+  direction: "up" | "down";
+}
+
+export interface HealthStatusSummary {
+  /** True when there is at least one deviation or one shift to surface. */
+  present: boolean;
+  deviations: HealthStatusDeviation[];
+  shifts: HealthStatusShift[];
+}
+
+/**
+ * Fold the band deviations + level shifts into the response shape. `vitals` is
+ * the full banded set from the coincident engine (any standing); only the
+ * out-of-band ones become deviations. `shifts` is the changepoint output as-is.
+ */
+export function summariseHealthStatus(
+  vitals: readonly VitalDeviation[],
+  shifts: readonly ChangepointSignal[],
+): HealthStatusSummary {
+  const deviations: HealthStatusDeviation[] = vitals
+    .filter((v) => v.outside && v.direction !== "in")
+    .map((v) => ({
+      type: v.type,
+      value: v.value,
+      center: v.center,
+      low: v.low,
+      high: v.high,
+      direction: v.direction === "above" ? "above" : "below",
+    }));
+
+  const mappedShifts: HealthStatusShift[] = shifts.map((s) => ({
+    metric: s.metric,
+    breakDate: s.breakDate,
+    beforeMean: s.beforeMean,
+    afterMean: s.afterMean,
+    direction: s.direction,
+  }));
+
+  return {
+    present: deviations.length + mappedShifts.length > 0,
+    deviations,
+    shifts: mappedShifts,
+  };
+}

src/lib/insights/labs-changes.ts

@@ -0,0 +1,131 @@
+/**
+ * v1.25 — "what changed since your last panel" shaping.
+ *
+ * Groups the user's numeric lab results by panel DATE (the calendar day of
+ * `takenAt`, UTC), finds the two most-recent dates, and for every analyte that
+ * appears in BOTH the latest and the previous panel reports the signed delta,
+ * the direction, and where the latest value sits against its reference band
+ * (`classifyReferenceRange`). Qualitative (valueText-only) results carry no
+ * numeric value, so they are skipped — a delta is meaningless for them.
+ *
+ * Pure + Prisma-free so the present / absent states are unit-testable: it is
+ * absent when there are fewer than two panel dates or no analyte is shared.
+ * Neutral framing only — a delta is not a diagnosis.
+ */
+import {
+  classifyReferenceRange,
+  type ReferenceRangeStatus,
+} from "@/lib/labs/reference-range";
+
+/** A single numeric lab reading. */
+export interface LabChangeRow {
+  analyte: string;
+  unit: string;
+  value: number;
+  referenceLow: number | null;
+  referenceHigh: number | null;
+  takenAt: Date;
+}
+
+export interface LabChange {
+  analyte: string;
+  unit: string;
+  latest: number;
+  previous: number;
+  /** Signed latest − previous, rounded to 2dp. */
+  delta: number;
+  direction: "up" | "down" | "flat";
+  status: ReferenceRangeStatus;
+}
+
+export interface LabChangesSummary {
+  present: boolean;
+  /** YYYY-MM-DD of the most-recent panel, or null when absent. */
+  latestDate: string | null;
+  /** YYYY-MM-DD of the prior panel, or null when absent. */
+  previousDate: string | null;
+  changes: LabChange[];
+}
+
+const ABSENT: LabChangesSummary = {
+  present: false,
+  latestDate: null,
+  previousDate: null,
+  changes: [],
+};
+
+/** UTC calendar-day key (YYYY-MM-DD) for a sample instant. */
+function dayKey(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+/** Normalised analyte name for cross-panel matching (free-text tolerant). */
+function analyteKey(analyte: string): string {
+  return analyte.trim().toLowerCase();
+}
+
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+
+/**
+ * Summarise the change between the two most-recent numeric lab panels. `rows`
+ * should already be the user's live (non-deleted) numeric results; this helper
+ * does the grouping + pairing.
+ */
+export function summariseLabChanges(
+  rows: readonly LabChangeRow[],
+): LabChangesSummary {
+  const numeric = rows.filter((r) => Number.isFinite(r.value));
+  if (numeric.length === 0) return ABSENT;
+
+  // Group by panel day, keeping the latest reading per analyte within a day.
+  const byDay = new Map<string, Map<string, LabChangeRow>>();
+  for (const row of numeric) {
+    const day = dayKey(row.takenAt);
+    let analytes = byDay.get(day);
+    if (!analytes) {
+      analytes = new Map();
+      byDay.set(day, analytes);
+    }
+    const key = analyteKey(row.analyte);
+    const existing = analytes.get(key);
+    if (!existing || row.takenAt.getTime() >= existing.takenAt.getTime()) {
+      analytes.set(key, row);
+    }
+  }
+
+  const days = [...byDay.keys()].sort((a, b) => (a < b ? 1 : a > b ? -1 : 0));
+  if (days.length < 2) return ABSENT;
+
+  const latestDate = days[0];
+  const previousDate = days[1];
+  const latest = byDay.get(latestDate)!;
+  const previous = byDay.get(previousDate)!;
+
+  const changes: LabChange[] = [];
+  for (const [key, latestRow] of latest) {
+    const previousRow = previous.get(key);
+    if (!previousRow) continue;
+    const delta = round2(latestRow.value - previousRow.value);
+    const direction: LabChange["direction"] =
+      delta > 0 ? "up" : delta < 0 ? "down" : "flat";
+    changes.push({
+      analyte: latestRow.analyte,
+      unit: latestRow.unit,
+      latest: latestRow.value,
+      previous: previousRow.value,
+      delta,
+      direction,
+      status: classifyReferenceRange(
+        latestRow.value,
+        latestRow.referenceLow,
+        latestRow.referenceHigh,
+      ),
+    });
+  }
+
+  if (changes.length === 0) return ABSENT;
+
+  changes.sort((a, b) => a.analyte.localeCompare(b.analyte));
+
+  return { present: true, latestDate, previousDate, changes };
+}