/** * The deterministic evidence block behind the per-workout Activity Insight. * * Everything the model is ever told about a session is built here, and the * shape of this module is the security boundary of the whole feature: it is a * NUMBERS-ONLY projection over closed fields. * * What is excluded, and why each one matters: * * - `metadata` — a JSON blob of device bundle ids, HKWorkoutEvent markers and * per-vendor extras. Never passed in at all; the only thing taken from it * anywhere on this path is the numeric WHOOP zone-duration array, and that * goes through `parseWhoopZoneDurations` before it gets near here. * - `externalId` — a vendor-supplied opaque string. Never selected. * - route geometry — consumed to derive ONE number (metres climbed) and then * dropped. It is location history, not a figure, and it may not ride a * prompt. * - `sportType` — a TEXT column. The API write path constrains it to * `workoutSportTypeEnum`, but the BACKUP RESTORE path accepts * `z.string().min(1)`, so a restored row can carry arbitrary * attacker-chosen text. It is therefore re-asserted against the enum HERE, * at projection time, and anything unrecognised folds to `"other"`. The * enum is imported from the schema module rather than copied, because a * hand-copied vocabulary drifts. * * And the claim is enforced by `assertNumericLeaves`, not by this comment: the * projection is walked before it is returned and ANY non-numeric leaf at any * depth throws. A future field that quietly admits a string fails loudly at the * seam instead of arriving in a prompt. * * Determinism is the second contract. The same session always projects to the * same numbers, which is what makes the input hash a real no-op gate: a WHOOP * re-sync or an iOS `stats:` overwrite that changes nothing the paragraph * narrates hashes identically and never reaches a provider. */ import { userDayKey } from "@/lib/tz/format"; import { workoutSportTypeEnum } from "@/lib/validations/workout"; import type { WorkoutHrSeries } from "./hr-series"; import type { WorkoutZones } from "./zones"; /** Lookback for the own-history comparison, in days. */ export const OWN_HISTORY_LOOKBACK_DAYS = 90; /** Cap on the history rows the median reads — bounded work on a heavy account. */ export const OWN_HISTORY_MAX_ROWS = 400; /** * The shape of the session's heart rate, reduced to four figures. * * Derived from the SAME series the detail route renders (`buildWorkoutHrSeries`), * deliberately not from `loadIntradayPulse`: that read is day-scoped, so it * would answer a question about the day rather than about the session, and the * workout-window series is the richer of the two anyway. */ export interface WorkoutHrShape { bucketSec: number; buckets: number; /** Mean bpm across the first half of the session's buckets. */ firstHalfMeanBpm: number; /** Mean bpm across the second half. */ secondHalfMeanBpm: number; /** secondHalf − firstHalf. Positive = drifting up as the session went on. */ driftBpm: number; /** Buckets that stand out as a local high point (see `countPeaks`). */ peaks: number; /** * Median seconds from a peak back down to the session's mean. Null when no * peak ever came back down inside the session. */ medianSettleSec: number | null; } /** The user's own recent baseline for this sport. Medians, never means. */ export interface WorkoutOwnHistory { lookbackDays: number; /** Comparable sessions found, excluding this one. */ sampleSize: number; medianDurationSec: number; medianAvgHr: number | null; medianDistanceM: number | null; medianEnergyKcal: number | null; } export interface WorkoutInsightEvidence { /** Narrowed against the closed enum — never the raw column. */ sportType: string; /** User-profile-timezone day the session started. */ localDate: string; durationSec: number; distanceM: number | null; /** Metres climbed, from route altitudes when present, else the column. */ climbM: number | null; activeEnergyKcal: number | null; avgHr: number | null; maxHr: number | null; minHr: number | null; /** Seconds in each %HRmax (or device) zone, ascending by zone. */ zoneSeconds: { zone: number; seconds: number }[] | null; hr: WorkoutHrShape | null; history: WorkoutOwnHistory | null; } /** * Narrow the stored sport string to the closed vocabulary. * * The DB column is free text by design (a new sport is one Zod refinement * away), so this is the whitelist that keeps an unreviewed value out of the * prompt. Anything unrecognised projects as `"other"` — the same bucket the * ingest validator uses. */ export function narrowSportType(raw: string): string { const parsed = workoutSportTypeEnum.safeParse(raw); return parsed.success ? parsed.data : "other"; } function median(values: number[]): number | null { const sorted = values.filter((v) => Number.isFinite(v)).sort((a, b) => a - b); if (sorted.length === 0) return null; const mid = Math.floor(sorted.length / 2); return sorted.length % 2 === 1 ? sorted[mid] : Math.round(((sorted[mid - 1] + sorted[mid]) / 2) * 10) / 10; } /** * How far above the session's own mean a bucket must sit to count as an effort. * * A percentile alone is not enough, and the reason is worth keeping: on a flat * ride the 90th percentile sits a beat or two above the mean, so ordinary * sampling noise clears it and a steady session reports several "peaks" that * the rider did not do. Five bpm is the smallest rise that is a change in * effort rather than a change in measurement. */ const MIN_PEAK_PROMINENCE_BPM = 5; /** * Count the session's peaks. * * A peak is a bucket that is a strict local maximum against its neighbours AND * clears both thresholds: the 90th percentile of the session's bucket means * (relative — it stands out for THIS session) and the prominence floor above * the session mean (absolute — it is a real rise, not noise). Requiring all * three is what keeps a steady ride from reporting efforts it did not contain * while an interval session still reports each of its own. */ function countPeaks(means: number[], threshold: number): number[] { const indices: number[] = []; for (let i = 1; i < means.length - 1; i++) { if ( means[i] >= threshold && means[i] > means[i - 1] && means[i] >= means[i + 1] ) { indices.push(i); } } return indices; } function percentile(sorted: number[], p: number): number { if (sorted.length === 0) return 0; const idx = Math.min( sorted.length - 1, Math.max(0, Math.round((sorted.length - 1) * p)), ); return sorted[idx]; } /** * Reduce the HR curve to the four figures the paragraph can honestly use. * * Returns null below three buckets: two points cannot carry a front/back-half * comparison, and inventing one from them is exactly the overclaiming the copy * contract forbids. */ export function summariseHrShape( series: WorkoutHrSeries | null, ): WorkoutHrShape | null { if (!series || series.points.length < 3) return null; const means = series.points.map((p) => p.mean); const half = Math.floor(means.length / 2); const avg = (xs: number[]) => Math.round((xs.reduce((a, b) => a + b, 0) / xs.length) * 10) / 10; const firstHalfMeanBpm = avg(means.slice(0, half)); const secondHalfMeanBpm = avg(means.slice(means.length - half)); const sessionMean = avg(means); const sorted = [...means].sort((a, b) => a - b); const peakIndices = countPeaks( means, Math.max(percentile(sorted, 0.9), sessionMean + MIN_PEAK_PROMINENCE_BPM), ); // Settle time: from each peak, how long until the curve first comes back to // the session's own mean. A peak that never settles inside the session // contributes nothing rather than a censored figure pretending to be one. const settles: number[] = []; for (const idx of peakIndices) { for (let j = idx + 1; j < means.length; j++) { if (means[j] <= sessionMean) { settles.push((j - idx) * series.bucketSec); break; } } } return { // `series.source` ("workout_series" | "pulse_window") is deliberately not // carried: it is provenance for the chart, it is a string, and the // paragraph has nothing to say about it. Dropping it keeps the projection // numeric without an allowlist exception. bucketSec: series.bucketSec, buckets: series.points.length, firstHalfMeanBpm, secondHalfMeanBpm, driftBpm: Math.round((secondHalfMeanBpm - firstHalfMeanBpm) * 10) / 10, peaks: peakIndices.length, medianSettleSec: settles.length > 0 ? median(settles) : null, }; } /** * Total metres climbed, summed from a GeoJSON LineString's altitude channel. * * Only positive deltas count — this is climb, not net elevation change, which * is the figure a rider recognises. Returns null when the geometry carries no * altitude channel at all (Withings ships static GPX without one), so the * caller can fall back to the denormalised column instead of reporting a * confident zero. */ export function routeClimbM(geometry: unknown): number | null { if (!geometry || typeof geometry !== "object") return null; const coords = (geometry as { coordinates?: unknown }).coordinates; if (!Array.isArray(coords)) return null; let climb = 0; let previous: number | null = null; let seen = 0; for (const point of coords) { if (!Array.isArray(point) || point.length < 3) continue; const alt = point[2]; if (typeof alt !== "number" || !Number.isFinite(alt)) continue; seen++; if (previous !== null && alt > previous) climb += alt - previous; previous = alt; } return seen >= 2 ? Math.round(climb) : null; } /** Slim row shape the own-history median reads. */ export interface OwnHistoryRow { durationSec: number; avgHeartRate: number | null; totalDistanceM: number | null; totalEnergyKcal: number | null; } /** * The user's own median for this sport over the lookback window. * * Medians rather than means because a single six-hour outing would drag a mean * far enough that the paragraph's comparison would be wrong in the ordinary * case. Returns null below three comparable sessions: two sessions do not make * a baseline, and the copy contract says so plainly instead. * * CONVERGENCE NOTE — read before editing. * * `src/lib/workouts/sport-context.ts` computes an own-history comparison for * the SAME sport, for the workout-detail card and the coach's evidence block. * The two are not interchangeable today and the differences are deliberate on * this side, but they should become one function: * * | this | sport-context.ts | * |-----------------------------|-----------------------------| * | 90-day lookback | 180-day lookback | * | medians | means | * | null below 3 sessions | any non-empty result | * * Medians and the three-session floor are the ones worth keeping: a paragraph * that says "right at your usual" must not be moved by one outlier or built on * a single prior session. The lookback is arbitrary on both sides. * * The caller MUST collapse cross-source twins through `pickCanonicalWorkoutRows` * before calling this, exactly as `sport-context.ts` does — a session recorded * by two paired watches is one session, and counting it twice inflates the * sample size and biases every median. */ export function summariseOwnHistory( rows: readonly OwnHistoryRow[], ): WorkoutOwnHistory | null { if (rows.length < 3) return null; const durations = rows.map((r) => r.durationSec); const medianDurationSec = median(durations); if (medianDurationSec === null) return null; const numeric = (pick: (r: OwnHistoryRow) => number | null): number[] => rows .map(pick) .filter((v): v is number => typeof v === "number" && Number.isFinite(v)); return { lookbackDays: OWN_HISTORY_LOOKBACK_DAYS, sampleSize: rows.length, medianDurationSec: Math.round(medianDurationSec), medianAvgHr: median(numeric((r) => r.avgHeartRate)), medianDistanceM: median(numeric((r) => r.totalDistanceM)), medianEnergyKcal: median(numeric((r) => r.totalEnergyKcal)), }; } /** The already-loaded workout row the projection reads. */ export interface WorkoutEvidenceRow { sportType: string; startedAt: Date; durationSec: number; totalDistanceM: number | null; totalEnergyKcal: number | null; avgHeartRate: number | null; maxHeartRate: number | null; minHeartRate: number | null; elevationM: number | null; } export interface BuildEvidenceInput { row: WorkoutEvidenceRow; tz: string; /** The detail route's HR curve for this workout, or null. */ hrSeries: WorkoutHrSeries | null; /** Zones as the detail route computes them, or null. */ zones: WorkoutZones | null; /** `WorkoutRoute.geometry`, or null when the source shipped no route. */ routeGeometry: unknown; /** Same-sport sessions inside the lookback, excluding this workout. */ history: readonly OwnHistoryRow[]; } /** * The only two string-valued leaves the projection is allowed to carry, each * with the shape that makes it safe. * * `sportType` is a member of the closed enum; `localDate` is a derived day key. * Neither can carry attacker text once these hold. Everything else must be a * number, a boolean, or null. */ const ALLOWED_STRING_LEAVES: Record = { sportType: new RegExp(`^(?:${workoutSportTypeEnum.options.join("|")})$`), localDate: /^\d{4}-\d{2}-\d{2}$/, }; /** * Walk the finished projection and throw on anything that is not a number. * * This is the enforcement behind the module's headline claim. A comment saying * "numbers only" is worth nothing the day someone adds a field: it stays true * in the docblock and false in the payload. Walking every leaf means the claim * fails at the seam, in the worker, before a provider is resolved — and the * worker treats a throw as a transient fault, so the paragraph is simply not * written rather than written from unvetted input. * * `hrSource` is deliberately NOT on the allowlist: the HR shape's `source` is a * two-value internal literal, and it is dropped from the projection entirely * rather than argued about. */ export function assertNumericLeaves(value: unknown, path = "evidence"): void { if ( value === null || typeof value === "number" || typeof value === "boolean" ) { if (typeof value === "number" && !Number.isFinite(value)) { throw new Error(`workout evidence: non-finite number at ${path}`); } return; } if (Array.isArray(value)) { value.forEach((entry, i) => assertNumericLeaves(entry, `${path}[${i}]`)); return; } if (typeof value === "object") { for (const [key, leaf] of Object.entries( value as Record, )) { const allowed = ALLOWED_STRING_LEAVES[key]; if (allowed) { if (typeof leaf !== "string" || !allowed.test(leaf)) { throw new Error( `workout evidence: ${path}.${key} is not a permitted ${key} value`, ); } continue; } assertNumericLeaves(leaf, `${path}.${key}`); } return; } throw new Error( `workout evidence: non-numeric leaf at ${path} (${typeof value})`, ); } /** * Compose the evidence block. Pure — every read has already happened. */ export function buildWorkoutInsightEvidence( input: BuildEvidenceInput, ): WorkoutInsightEvidence { const { row } = input; const evidence: WorkoutInsightEvidence = { sportType: narrowSportType(row.sportType), localDate: userDayKey(row.startedAt, input.tz), durationSec: row.durationSec, distanceM: row.totalDistanceM, climbM: routeClimbM(input.routeGeometry) ?? row.elevationM, activeEnergyKcal: row.totalEnergyKcal, avgHr: row.avgHeartRate, maxHr: row.maxHeartRate, minHr: row.minHeartRate, zoneSeconds: input.zones?.zones.map((z) => ({ zone: z.zone, seconds: z.seconds })) ?? null, hr: summariseHrShape(input.hrSeries), history: summariseOwnHistory(input.history), }; assertNumericLeaves(evidence); return evidence; }