/** * Intraday pulse shape + the elevated-at-rest ("tension") window. * * Two deterministic, IO-free computations that reveal the SHAPE of a single * day's heart rate and, cautiously, whether a stretch of it looks like tension * rather than exercise: * * 1. `computeTenMinuteMeanSeries` — folds the day's raw PULSE samples into * 10-minute means in the user's local time. Computed ON DEMAND for the * viewed day (read-swap; the same fold the hourly-mean retention uses), * never persisted as 10-min rollups for all history. * 2. `detectTensionWindow` — the differentiator. The tension signal is NOT * raw HR (that conflates a workout with stress): it is heart rate * SUSTAINED above the user's personal RESTING baseline WHILE movement is * low — the "elevated-at-rest window". A workout-overlapping or * high-step bucket can never qualify, so a hard run does not read as * tension. Where intraday HRV exists (WHOOP), it is surfaced as a * confirming flag but is never required. * * The launch posture is deliberately conservative — "says less than it could". * A window is only reported when baseline maturity, per-bucket sample density, * a mandatory low-movement gate, and a minimum sustained duration ALL hold. * Silence over speculation. This is descriptive context, never a clinical * stress diagnosis. * * Pure & deterministic — unit-tested in `__tests__/intraday-pulse.test.ts`. */ import { formatInUserTz } from "@/lib/tz/format"; /** Intraday bucket width, in minutes. Ten minutes reveals the day's shape. */ export const BUCKET_MINUTES = 10; /** * S11 day-navigator fallback bucket width, in minutes. Days older than * `DENSE_INTRADAY_RETENTION_DAYS` (`dense-intraday-retention.ts`) have their * raw per-sample rows folded to one `stats:` hourly-mean row per local hour; * `computeHourlyMeanSeries` re-buckets those at this coarser grain instead of * pretending they carry 10-minute resolution. */ export const HOURLY_BUCKET_MINUTES = 60; /** * The resolution the intraday series was actually computed at — surfaced on * the DTO so the chart can label a folded, older day honestly instead of * implying every day carries the same 10-minute detail. `"tenMin"` reads * raw per-sample rows; `"hourly"` reads the folded `stats:` tier * (`loadIntradayPulse`'s fallback for a day outside the dense retention * window). The tension-window detector requires `"tenMin"` resolution — see * `detectTensionWindow`'s docblock. */ export type IntradayResolution = "tenMin" | "hourly"; /** * A 10-minute bucket needs at least this many raw samples before it is * TRUSTED as a mean. A lone reading is a point, not a bucket — trusting it * would let a single spike masquerade as a sustained stretch. Sub-floor * buckets are treated as gaps that BREAK a candidate run (density gate). */ export const MIN_SAMPLES_PER_BUCKET = 2; /** * How far above the resting baseline a bucket's mean must sit to count as * "elevated". Twelve bpm keeps normal ambient drift (standing, a warm room, * digestion) below the line — only a genuine, sustained lift clears it. The * bar is deliberately high; under-flagging is the intended failure mode. */ export const ELEVATION_MARGIN_BPM = 12; /** * Steps within a 10-minute bucket at or above this count mark the bucket as * MOVING — a walk the raw HR would otherwise read as an elevated-at-rest * stretch. Sixty steps in ten minutes is a slow amble; anything at or above * it disqualifies the bucket from the tension window. */ export const STEP_MOVEMENT_THRESHOLD = 60; /** * A day needs at least this many step buckets before a low / absent step * reading can be TRUSTED as "genuinely not moving" rather than "steps simply * weren't recorded". Below this coverage the low-movement gate cannot be * satisfied and no window is reported — the movement gate is mandatory, and a * missing step stream is silence, not evidence of rest. */ export const MIN_STEP_COVERAGE_BUCKETS = 6; /** * The minimum run of consecutive qualifying buckets before a window is * reported: three 10-minute buckets = 30 sustained minutes. A single elevated * bucket (a flight of stairs, a phone call) is noise; half an hour of * elevated-at-rest heart rate is a shape worth a cautious word. */ export const MIN_SUSTAINED_BUCKETS = 3; /** * Minimum number of resting-baseline days before the baseline is mature enough * to judge a single day against. A baseline built from two readings is not a * personal norm yet — until it matures, no window is reported. */ export const MIN_BASELINE_DAYS = 7; /** A timestamped heart-rate sample (raw PULSE). */ export interface IntradaySample { measuredAt: Date; value: number; } /** A 10-minute mean bucket, anchored on its start minute-of-local-day. */ export interface IntradayHrBucket { /** Minutes since local midnight at the bucket's start (0, 10, 20, …). */ startMinute: number; /** Mean of the raw samples that fell in the bucket. */ mean: number; /** Raw sample count — buckets below `MIN_SAMPLES_PER_BUCKET` are gaps. */ count: number; /** * v1.30.7 — the bucket's low / high bpm, when known: the min/max of the raw * samples (raw path) or the device-supplied `discreteMin`/`discreteMax` (an * uploaded 10-min bucket). Absent when the source carries no spread. Drives * the intraday envelope band around `mean`. */ min?: number; max?: number; } /** A workout's local-day span, in minutes since local midnight. */ export interface WorkoutInterval { startMinute: number; endMinute: number; } /** Coarse part-of-day label a window's midpoint falls in. */ export type PartOfDay = "morning" | "afternoon" | "evening" | "night"; /** A detected elevated-at-rest window — a cautious tension marker. */ export interface TensionWindow { /** Window start / end, minutes since local midnight. */ startMinute: number; endMinute: number; /** Part of day the window's midpoint falls in (drives the copy). */ partOfDay: PartOfDay; /** Mean HR across the window's buckets. */ meanHr: number; /** The resting baseline the window was judged against. */ baseline: number; /** True when intraday HRV independently confirmed the stretch (WHOOP). */ hrvConfirmed: boolean; } /** Local wall-clock projection of an instant: day key + minute-of-day. */ export interface LocalWallClock { dayKey: string; minuteOfDay: number; } /** Resolves an instant to the viewer's local day key + minute-of-day. */ export type LocalResolver = (d: Date) => LocalWallClock; /** * Build a `LocalResolver` for a timezone from the shared tz formatter. Kept * here so the pure computations stay tz-correct without every caller * re-deriving the wall-clock math; tests inject their own resolver for * deterministic, tz-free fixtures. */ export function makeLocalResolver(tz: string): LocalResolver { return (d: Date) => { // "YYYY-MM-DD HH:mm" in the target zone — one formatter, no drift. const wall = formatInUserTz(d, tz, "datetime"); const [dayKey, clock] = wall.split(" "); const [hh, mm] = clock.split(":"); return { dayKey, minuteOfDay: parseInt(hh, 10) * 60 + parseInt(mm, 10), }; }; } /** Round to one decimal — keeps the mean readable without false precision. */ function round1(n: number): number { return Math.round(n * 10) / 10; } /** * Fold a day's raw PULSE samples into ascending 10-minute mean buckets. Only * samples whose LOCAL day matches `dayKey` participate, so a 23:55-local * reading never bleeds into the next day's shape. Empty or sparse buckets are * simply absent — the series is the buckets that exist, not a padded grid. */ export function computeTenMinuteMeanSeries( samples: ReadonlyArray, dayKey: string, localOf: LocalResolver, ): IntradayHrBucket[] { const acc = new Map< number, { sum: number; count: number; min: number; max: number } >(); for (const s of samples) { const local = localOf(s.measuredAt); if (local.dayKey !== dayKey) continue; const startMinute = Math.floor(local.minuteOfDay / BUCKET_MINUTES) * BUCKET_MINUTES; const bucket = acc.get(startMinute); if (bucket) { bucket.sum += s.value; bucket.count += 1; bucket.min = Math.min(bucket.min, s.value); bucket.max = Math.max(bucket.max, s.value); } else { acc.set(startMinute, { sum: s.value, count: 1, min: s.value, max: s.value, }); } } return [...acc.entries()] .map(([startMinute, { sum, count, min, max }]) => ({ startMinute, mean: round1(sum / count), count, // v1.30.7 — carry the raw spread for the envelope band, for parity with // an uploaded bucket's device-supplied min/max. min: round1(min), max: round1(max), })) .sort((a, b) => a.startMinute - b.startMinute); } /** * v1.30.7 (iOS #34) — build the 10-minute series directly from UPLOADED * aggregated HR buckets (`stats:HKQuantityTypeIdentifierHeartRate:<10-min-Z>` * rows), one bucket per slot. Each row already IS a 10-minute mean, so it maps * 1:1 to a plotted point; `min`/`max` carry the device's `discreteMin`/`Max`. * * A device-computed bucket statistic summarises many raw samples the client * aggregated on-device, so it is treated as DENSE — assigned a synthetic * `count` of `MIN_SAMPLES_PER_BUCKET` so tension detection stays enabled on a * bucket-native day (the wire carries no sample count; see the contract doc's * open-risks note on the density gate). * * `bucketStart` is the canonical UTC 10-min boundary from the externalId * (resolved to the local slot), NOT the row's `measuredAt` (which carries the * display offset). Last write wins on the rare slot collision (:45-offset * zones can skew two UTC buckets toward one local slot). */ export function computeUploadedBucketSeries( buckets: ReadonlyArray<{ bucketStart: Date; mean: number; min: number | null; max: number | null; }>, dayKey: string, localOf: LocalResolver, ): IntradayHrBucket[] { const acc = new Map(); for (const b of buckets) { const local = localOf(b.bucketStart); if (local.dayKey !== dayKey) continue; const startMinute = Math.floor(local.minuteOfDay / BUCKET_MINUTES) * BUCKET_MINUTES; acc.set(startMinute, { startMinute, mean: round1(b.mean), count: MIN_SAMPLES_PER_BUCKET, ...(b.min != null ? { min: round1(b.min) } : {}), ...(b.max != null ? { max: round1(b.max) } : {}), }); } return [...acc.values()].sort((a, b) => a.startMinute - b.startMinute); } /** * Fold a day's already-folded `stats:` hourly-mean rows into ascending * per-local-hour buckets — the day-navigator's fallback shape for a day * outside the dense retention window, where the raw per-sample rows are * long tombstoned and only the hourly means survive live. Only samples * whose LOCAL day matches `dayKey` participate, same as * `computeTenMinuteMeanSeries`. Bucket `count` reflects how many `stats:` * rows landed in that local hour — normally exactly one (the dense-tier * fold mints at most one hourly row per hour), so the density gate in * `detectTensionWindow` would reject every bucket outright; callers must * not feed this series into tension detection regardless (see * `IntradayResolution`). */ export function computeHourlyMeanSeries( samples: ReadonlyArray, dayKey: string, localOf: LocalResolver, ): IntradayHrBucket[] { const acc = new Map(); for (const s of samples) { const local = localOf(s.measuredAt); if (local.dayKey !== dayKey) continue; const startMinute = Math.floor(local.minuteOfDay / HOURLY_BUCKET_MINUTES) * HOURLY_BUCKET_MINUTES; const bucket = acc.get(startMinute); if (bucket) { bucket.sum += s.value; bucket.count += 1; } else { acc.set(startMinute, { sum: s.value, count: 1 }); } } return [...acc.entries()] .map(([startMinute, { sum, count }]) => ({ startMinute, mean: round1(sum / count), count, })) .sort((a, b) => a.startMinute - b.startMinute); } /** Coarse part-of-day for a minute-of-day (drives the cautious copy). */ export function partOfDayForMinute(minute: number): PartOfDay { const hour = Math.floor(minute / 60); if (hour < 6) return "night"; if (hour < 12) return "morning"; if (hour < 18) return "afternoon"; return "evening"; } /** Whether a 10-minute bucket [start, start+10) intersects any workout. */ function overlapsWorkout( startMinute: number, workouts: ReadonlyArray, ): boolean { const end = startMinute + BUCKET_MINUTES; return workouts.some((w) => w.startMinute < end && w.endMinute > startMinute); } export interface DetectTensionInput { /** The day's 10-minute HR buckets (any order; re-sorted internally). */ buckets: ReadonlyArray; /** Personal resting baseline (bpm), or null when unknown. */ baseline: number | null; /** Whether the baseline is built from enough history to trust. */ baselineMature: boolean; /** Steps per 10-minute bucket, keyed by bucket start minute. */ stepBuckets: ReadonlyMap; /** Workout spans (local minutes) — buckets overlapping one never qualify. */ workouts: ReadonlyArray; /** Bucket start-minutes where intraday HRV independently confirms (WHOOP). */ hrvConfirmMinutes?: ReadonlyArray; } /** * Detect at most ONE elevated-at-rest window for the day, or null. A bucket * qualifies only when it is (a) elevated ≥ `baseline + ELEVATION_MARGIN_BPM`, * (b) NOT overlapping a workout, and (c) low-movement — its step count is below * `STEP_MOVEMENT_THRESHOLD` AND the day has enough step coverage to trust that * reading. The longest run of ≥ `MIN_SUSTAINED_BUCKETS` consecutive qualifying * buckets becomes the window (earliest wins a tie). Every gate must hold; when * any fails, the honest answer is no window. * * Callers must only invoke this against `"tenMin"`-resolution buckets * (`computeTenMinuteMeanSeries`) — never the `"hourly"` day-navigator * fallback (`computeHourlyMeanSeries`). A tension read needs per-sample * resolution to sustain the run/density gates honestly; an hourly mean would * either starve every bucket via the density gate (misleadingly silent) or, * worse, pass it on a coincidence of the hourly average. `loadIntradayPulse` * enforces this by only calling `detectTensionWindow` for `"tenMin"` days. */ export function detectTensionWindow( input: DetectTensionInput, ): TensionWindow | null { const { baseline, baselineMature, stepBuckets, workouts } = input; // Gate 1 — baseline maturity. No personal norm yet ⇒ say nothing. if (baseline == null || !baselineMature) return null; // Gate 2 — movement is MANDATORY and step-based. Without enough step // coverage a low/absent reading is "not recorded", not "not moving", so the // low-movement gate can never be satisfied and no window is reported. if (stepBuckets.size < MIN_STEP_COVERAGE_BUCKETS) return null; const threshold = baseline + ELEVATION_MARGIN_BPM; const hrvMinutes = new Set(input.hrvConfirmMinutes ?? []); // Only density-passing buckets participate; a sparse bucket is a gap that // breaks a run (we cannot assert "sustained" across missing data). const valid = [...input.buckets] .filter((b) => b.count >= MIN_SAMPLES_PER_BUCKET) .sort((a, b) => a.startMinute - b.startMinute); const qualifies = (b: IntradayHrBucket): boolean => { if (b.mean < threshold) return false; if (overlapsWorkout(b.startMinute, workouts)) return false; const steps = stepBuckets.get(b.startMinute) ?? 0; return steps < STEP_MOVEMENT_THRESHOLD; }; // Longest run of CONSECUTIVE qualifying buckets (consecutive = adjacent // 10-minute slots; any non-qualifying or missing slot breaks the run). let best: IntradayHrBucket[] = []; let run: IntradayHrBucket[] = []; for (const b of valid) { const prev = run[run.length - 1]; const consecutive = prev && b.startMinute === prev.startMinute + BUCKET_MINUTES; if (qualifies(b)) { run = consecutive ? [...run, b] : [b]; } else { run = []; } if (run.length > best.length) best = run; } if (best.length < MIN_SUSTAINED_BUCKETS) return null; const startMinute = best[0].startMinute; const endMinute = best[best.length - 1].startMinute + BUCKET_MINUTES; const meanHr = round1(best.reduce((sum, b) => sum + b.mean, 0) / best.length); const hrvConfirmed = best.some((b) => hrvMinutes.has(b.startMinute)); return { startMinute, endMinute, partOfDay: partOfDayForMinute(Math.floor((startMinute + endMinute) / 2)), meanHr, baseline, hrvConfirmed, }; }