trainbud 0.5.0

package/dist/detect/detectors.js

@@ -0,0 +1,291 @@
+import { buildBaseline, meanOf, median, robustZ } from "./baseline.js";
+import { dailyTrimp, estimateHrProfile } from "./trimp.js";
+// SECTION: Detectors
+//
+// One function per signal, each pure, each returning a Finding or null. Nothing
+// here calls a model: a language model asked to spot a trend will phrase a
+// hallucinated one exactly as confidently as a real one, and this project's
+// entire bug history is numbers being silently wrong. Code decides; the model
+// only ever phrases what code decided.
+const BASELINE_DAYS = 28;
+const RECENT_DAYS = 3;
+const SLEEP_WEEK_DAYS = 7;
+/** Robust-z at which a run of days stops looking like night-to-night noise. */
+const ELEVATION_Z = 2;
+/**
+ * A statistically large move can still be physiologically meaningless. Without
+ * this floor, a very consistent sleeper gets flagged over 1 bpm.
+ */
+const ELEVATION_MIN_BPM = 3;
+const SLEEP_DEBT_HOURS = 3;
+/**
+ * How far below the median a night has to fall before it counts as short at
+ * all. Half an hour, or the user's own spread, whichever is larger -- see the
+ * note in detectSleepDebt for the measurement that made this necessary.
+ */
+const SLEEP_NOISE_FLOOR_SECONDS = 30 * 60;
+const HRV_DROP_Z = -2;
+/**
+ * The recent window is held out of the baseline. Left in, a three-day
+ * elevation lifts the very median it is being measured against, and the longer
+ * something persists the more normal it looks -- which is backwards.
+ *
+ * Split by DATE, not by position. `slice(-3)` takes the last three points, and
+ * three points are only three days when the store has no holes -- which it
+ * routinely does, because a day only gets a row when the watch was actually
+ * worn. Take a user who wore the watch for three days in June, stopped, and
+ * picked it up again in August: the last three points spanned two months and a
+ * resting heart rate elevated in June was reported as "3 days running" today.
+ * Every detector that calls this inherited the same error, and the finding it
+ * produced was about a run of days that never happened.
+ */
+function split(points, recentDays, now) {
+    const cutoff = now.startOf("day").minus({ days: recentDays }).toISODate() ?? "";
+    const baselinePoints = [];
+    const recentPoints = [];
+    for (const point of points) {
+        if (point.date > cutoff) {
+            recentPoints.push(point);
+        }
+        else {
+            baselinePoints.push(point);
+        }
+    }
+    return { baselinePoints, recentPoints };
+}
+function round(value, places = 1) {
+    const factor = 10 ** places;
+    return Math.round(value * factor) / factor;
+}
+function lastDate(points, fallback) {
+    return points.at(-1)?.date ?? fallback;
+}
+/**
+ * How far this person's recent resting heart rate sits above their own median,
+ * whether or not that is far enough to be a finding.
+ *
+ * Split out because two things need it and only one of them is a threshold. The
+ * detector fires at a fixed bar; the colour on a watch card is graded against
+ * the band the user chose, which may be tighter or looser. Deriving the colour
+ * from "did a finding fire" would mean the card could only ever be green or
+ * red, and would move whenever the detector's own constants moved.
+ *
+ * Null when there is not enough history to have a baseline at all -- which is
+ * different from a delta of zero, and has to stay different.
+ */
+export function restingHrDeltaBpm(input) {
+    const points = input.series("resting_hr", BASELINE_DAYS + RECENT_DAYS);
+    const { baselinePoints, recentPoints } = split(points, RECENT_DAYS, input.now);
+    if (recentPoints.length === 0) {
+        return null;
+    }
+    const baseline = buildBaseline(baselinePoints);
+    const recentMean = meanOf(recentPoints);
+    if (!baseline || recentMean === null) {
+        return null;
+    }
+    return round(recentMean - baseline.median);
+}
+export function detectRestingHrElevation(input) {
+    const points = input.series("resting_hr", BASELINE_DAYS + RECENT_DAYS);
+    const { baselinePoints, recentPoints } = split(points, RECENT_DAYS, input.now);
+    if (recentPoints.length < RECENT_DAYS) {
+        return null;
+    }
+    const baseline = buildBaseline(baselinePoints);
+    if (!baseline) {
+        return null;
+    }
+    // Every one of the recent days must clear both bars. A single normal morning
+    // inside the run means it is not a run.
+    const elevated = recentPoints.every((point) => {
+        const z = robustZ(point.value, baseline);
+        return z !== null && z >= ELEVATION_Z && point.value - baseline.median >= ELEVATION_MIN_BPM;
+    });
+    if (!elevated) {
+        return null;
+    }
+    const recentMean = meanOf(recentPoints);
+    if (recentMean === null) {
+        return null;
+    }
+    const deltaBpm = round(recentMean - baseline.median);
+    return {
+        kind: "rhr_elevated",
+        severity: deltaBpm >= 6 ? "warn" : "notice",
+        date: lastDate(recentPoints, input.now.toISODate() ?? ""),
+        headline: `Resting heart rate ${deltaBpm} bpm above your ${baseline.count}-day baseline, ${RECENT_DAYS} days running`,
+        detail: "A run like this usually means the last few sessions have not been absorbed yet. Easy training or a rest day is the low-risk call until it settles.",
+        values: {
+            days: RECENT_DAYS,
+            recentBpm: round(recentMean),
+            baselineBpm: round(baseline.median),
+            deltaBpm,
+        },
+    };
+}
+export function detectSleepDebt(input) {
+    const points = input.series("sleep_seconds", BASELINE_DAYS + SLEEP_WEEK_DAYS);
+    const { baselinePoints, recentPoints } = split(points, SLEEP_WEEK_DAYS, input.now);
+    // A week with most of its nights missing is not a week with a deficit.
+    if (recentPoints.length < 5) {
+        return null;
+    }
+    const baseline = buildBaseline(baselinePoints);
+    if (!baseline) {
+        return null;
+    }
+    // Only shortfalls count. A long Saturday does not repay a short Tuesday --
+    // netting them out is how a chronically short week reads as fine.
+    //
+    // But shortfalls have to be measured against a floor, not against the median.
+    // Half of anyone's nights fall below their own median by construction, so
+    // summing one-sided gaps against it accumulates "debt" out of ordinary
+    // variation: for a symmetric sleeper the expected shortfall is about 0.4x the
+    // spread per night, so a week collects ~2.8x the spread before anything has
+    // actually gone wrong. Measured over 2000 synthetic steady sleepers with no
+    // deficit whatsoever, this fired on 5.7% of weeks at half an hour of
+    // night-to-night variation, 27% at three quarters of an hour, and 46.7% at a
+    // full hour -- which is an ordinary amount of variation for an ordinary
+    // person. Nearly half of all "sleep debt" findings were noise, and every test
+    // here used a perfectly constant series, where the spread is zero and the bias
+    // cannot appear.
+    //
+    // The floor is the user's own spread, with a half-hour minimum so a
+    // metronomic sleeper is not held to the minute. A night inside normal
+    // variation contributes nothing; a night genuinely short still contributes
+    // everything below the floor.
+    //
+    // Re-measured after the change, same 2000 trials: false positives fall to
+    // 0.0 / 1.6 / 8.0 / 14.4 / 23.7 percent across the same spreads, while a
+    // sleeper genuinely an hour short every night is still caught 67.9% of the
+    // time, 1.5 h short 93.0%, and 2 h short 99.7%. The sensitivity that matters
+    // is kept; nearly all of the noise is gone.
+    const floor = baseline.median - Math.max(SLEEP_NOISE_FLOOR_SECONDS, baseline.mad);
+    const debtSeconds = recentPoints.reduce((total, point) => {
+        return total + Math.max(0, floor - point.value);
+    }, 0);
+    const debtHours = round(debtSeconds / 3600);
+    if (debtHours < SLEEP_DEBT_HOURS) {
+        return null;
+    }
+    return {
+        kind: "sleep_debt",
+        severity: debtHours >= 6 ? "warn" : "notice",
+        date: lastDate(recentPoints, input.now.toISODate() ?? ""),
+        headline: `${debtHours} h of sleep short of your usual ${round(baseline.median / 3600)} h over the last ${recentPoints.length} nights`,
+        detail: "Short weeks blunt what hard sessions give back. Worth protecting the next few nights before the next quality session.",
+        values: {
+            debtHours,
+            nights: recentPoints.length,
+            baselineHours: round(baseline.median / 3600),
+        },
+    };
+}
+export function detectHrvTrendBreak(input) {
+    const points = input.series("hrv_overnight", BASELINE_DAYS + RECENT_DAYS);
+    const { baselinePoints, recentPoints } = split(points, RECENT_DAYS, input.now);
+    if (recentPoints.length < RECENT_DAYS) {
+        return null;
+    }
+    const baseline = buildBaseline(baselinePoints);
+    if (!baseline) {
+        return null;
+    }
+    // The median of the recent nights, not their mean. HRV is noisy enough that
+    // one low reading says almost nothing, and a mean lets a single bad night
+    // drag the window past the threshold on its own -- which is the very outlier
+    // problem the baseline uses a median to avoid. With a median, two of the
+    // three nights have to be low before this fires.
+    const recentMedian = median(recentPoints.map((point) => point.value));
+    if (recentMedian === null) {
+        return null;
+    }
+    const z = robustZ(recentMedian, baseline);
+    if (z === null || z > HRV_DROP_Z) {
+        return null;
+    }
+    return buildHrvFinding(recentPoints, recentMedian, baseline, input);
+}
+function buildHrvFinding(recentPoints, recentMedian, baseline, input) {
+    const dropPercent = round(((baseline.median - recentMedian) / baseline.median) * 100);
+    return {
+        kind: "hrv_trend_break",
+        severity: dropPercent >= 20 ? "warn" : "notice",
+        date: lastDate(recentPoints, input.now.toISODate() ?? ""),
+        headline: `Overnight HRV ${dropPercent}% below your ${baseline.count}-day baseline across ${recentPoints.length} nights`,
+        detail: "A multi-night drop is the usual sign that recovery is lagging the training. Keep the next session easy and see whether it comes back.",
+        values: {
+            nights: recentPoints.length,
+            recentMedian: round(recentMedian),
+            baseline: round(baseline.median),
+            dropPercent,
+        },
+    };
+}
+// SECTION: Training load
+//
+// Acute (7-day TRIMP) against chronic (28-day TRIMP, expressed weekly). The
+// classic injury-risk flag, and the one signal here that actually joins
+// training to recovery rather than reading a wellness metric on its own.
+const ACUTE_DAYS = 7;
+const CHRONIC_DAYS = 28;
+const RATIO_HIGH = 1.5;
+const RATIO_LOW = 0.8;
+/**
+ * A chronic average taken over a hole in the store makes every ratio look
+ * alarming, so most of the window has to actually be covered before a number is
+ * worth reporting.
+ */
+const MIN_CHRONIC_COVERAGE_DAYS = 21;
+export function detectLoadRatio(input) {
+    const profile = estimateHrProfile(input.series("resting_hr", CHRONIC_DAYS), input.series("max_hr", CHRONIC_DAYS));
+    if (!profile) {
+        return null;
+    }
+    const coverage = input.series("resting_hr", CHRONIC_DAYS).length;
+    if (coverage < MIN_CHRONIC_COVERAGE_DAYS) {
+        return null;
+    }
+    const byDay = dailyTrimp(input.activities(CHRONIC_DAYS), profile);
+    const today = input.now.startOf("day");
+    const sumOverDays = (days) => {
+        let total = 0;
+        for (let offset = 0; offset < days; offset += 1) {
+            const date = today.minus({ days: offset }).toISODate();
+            if (date) {
+                total += byDay.get(date) ?? 0;
+            }
+        }
+        return total;
+    };
+    const acute = sumOverDays(ACUTE_DAYS);
+    const chronicWeekly = sumOverDays(CHRONIC_DAYS) / (CHRONIC_DAYS / ACUTE_DAYS);
+    // Nothing to compare against: a first week of training is not a spike.
+    if (chronicWeekly <= 0) {
+        return null;
+    }
+    const ratio = round(acute / chronicWeekly, 2);
+    if (ratio <= RATIO_HIGH && ratio >= RATIO_LOW) {
+        return null;
+    }
+    const isHigh = ratio > RATIO_HIGH;
+    const provenance = "This load is TRIMP, computed here from duration and heart rate, so it will not match the training load Connect shows.";
+    return {
+        kind: isHigh ? "load_ratio_high" : "load_ratio_low",
+        severity: isHigh && ratio >= 2 ? "warn" : "notice",
+        date: today.toISODate() ?? "",
+        headline: isHigh
+            ? `This week's training load is ${ratio}x your four-week average`
+            : `This week's training load is down to ${ratio}x your four-week average`,
+        detail: isHigh
+            ? `Jumps this size are where injuries tend to come from. Holding the next week nearer the average is the low-risk call. ${provenance}`
+            : `A drop this size for more than a week or two starts costing fitness rather than building it. ${provenance}`,
+        values: {
+            ratio,
+            acuteLoad: round(acute),
+            chronicWeeklyLoad: round(chronicWeekly),
+        },
+    };
+}
+//# sourceMappingURL=detectors.js.map

package/dist/detect/detectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectors.js","sourceRoot":"","sources":["../../src/detect/detectors.ts"],"names":[],"mappings":"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"}

package/dist/detect/findings.d.ts

@@ -0,0 +1,29 @@
+import type { DateTime } from "luxon";
+import type { MetricKind } from "../history/schema.js";
+import type { MetricPoint, StoredActivity } from "../history/store.js";
+export type FindingKind = "rhr_elevated" | "sleep_debt" | "hrv_trend_break" | "load_ratio_high" | "load_ratio_low";
+export type FindingSeverity = "info" | "notice" | "warn";
+export interface Finding {
+    kind: FindingKind;
+    severity: FindingSeverity;
+    /** The day the finding is about, which is the most recent day it covers. */
+    date: string;
+    /** The measurement, in plain language. Never a cause. */
+    headline: string;
+    /** What it means for training. Never medical. */
+    detail: string;
+    /** The numbers behind the headline, for a surface that wants to render them. */
+    values: Record<string, number>;
+}
+/**
+ * Detectors read through this rather than reaching for the store, which is what
+ * keeps every one of them a pure function over arrays and their tests free of a
+ * database.
+ */
+export interface DetectorInput {
+    now: DateTime;
+    /** Points for the last `days` days, oldest first. */
+    series: (kind: MetricKind, days: number) => MetricPoint[];
+    activities: (days: number) => StoredActivity[];
+}
+//# sourceMappingURL=findings.d.ts.map

package/dist/detect/findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../../src/detect/findings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAavE,MAAM,MAAM,WAAW,GACnB,cAAc,GACd,YAAY,GACZ,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,CAAC;IACd,qDAAqD;IACrD,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,WAAW,EAAE,CAAC;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,EAAE,CAAC;CAChD"}

package/dist/detect/findings.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=findings.js.map

package/dist/detect/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../src/detect/findings.ts"],"names":[],"mappings":""}

package/dist/detect/forecast.d.ts

@@ -0,0 +1,33 @@
+import type { DetectorInput } from "./findings.js";
+export type LoadTrajectory = "rising" | "falling" | "steady";
+export type LoadVerdict = "spike_ahead" | "detraining_ahead" | "on_track" | "unknown";
+export interface LoadForecast {
+    /** Where the ratio is today. Null when there is not enough history to say. */
+    currentRatio: number | null;
+    /** Where it lands in seven days if this week repeats. */
+    projectedRatio: number | null;
+    trajectory: LoadTrajectory;
+    verdict: LoadVerdict;
+    /** TRIMP over the last seven days. */
+    acuteLoad: number;
+    /** TRIMP over the last 28 days, expressed as a weekly figure. */
+    chronicWeeklyLoad: number;
+    /**
+     * How much this week's load would have to change to land inside the safe
+     * band. Positive means add load, negative means shed it. Null when already
+     * inside the band or when there is nothing to compare against.
+     */
+    weeklyLoadAdjustment: number | null;
+    /** Plain sentence for a watch screen or a model prompt. Never medical. */
+    summary: string;
+}
+/**
+ * The projection has to move the whole 28-day window, not just add to it.
+ *
+ * A week from now the chronic window has dropped its oldest seven days and
+ * gained the seven we are projecting. Holding chronic fixed and only advancing
+ * acute overstates the ratio whenever the dropped week was heavy -- which is
+ * precisely the case where the user most needs the number to be right.
+ */
+export declare function forecastLoad(input: DetectorInput): LoadForecast;
+//# sourceMappingURL=forecast.d.ts.map

package/dist/detect/forecast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forecast.d.ts","sourceRoot":"","sources":["../../src/detect/forecast.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAsBnD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAC7D,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,kBAAkB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtF,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yDAAyD;IACzD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,cAAc,CAAC;IAC3B,OAAO,EAAE,WAAW,CAAC;IACrB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CA6G/D"}

package/dist/detect/forecast.js

@@ -0,0 +1,122 @@
+import { dailyTrimp, estimateHrProfile } from "./trimp.js";
+// SECTION: Training load forecast
+//
+// The acute:chronic ratio detector says where the ratio is. It fires after the
+// jump, which is the wrong side of the event: the value of the ratio is that it
+// warns you *before* the week that hurts you, and a warning that arrives once
+// the week is over is a diary entry.
+//
+// This projects the ratio forward one week on the only assumption the data
+// itself supports: that the next seven days look like the last seven. It is an
+// extrapolation and it is labelled as one. Nothing here asks the user to record
+// a plan, because a forecast that depends on the user diligently logging their
+// intentions is a forecast that will be wrong exactly when they are busy -- and
+// being busy is correlated with the training weeks that go wrong.
+const ACUTE_DAYS = 7;
+const CHRONIC_DAYS = 28;
+const RATIO_HIGH = 1.5;
+const RATIO_LOW = 0.8;
+const MIN_CHRONIC_COVERAGE_DAYS = 21;
+function round(value, places = 2) {
+    const factor = 10 ** places;
+    return Math.round(value * factor) / factor;
+}
+/**
+ * The projection has to move the whole 28-day window, not just add to it.
+ *
+ * A week from now the chronic window has dropped its oldest seven days and
+ * gained the seven we are projecting. Holding chronic fixed and only advancing
+ * acute overstates the ratio whenever the dropped week was heavy -- which is
+ * precisely the case where the user most needs the number to be right.
+ */
+export function forecastLoad(input) {
+    const unknown = {
+        currentRatio: null,
+        projectedRatio: null,
+        trajectory: "steady",
+        verdict: "unknown",
+        acuteLoad: 0,
+        chronicWeeklyLoad: 0,
+        weeklyLoadAdjustment: null,
+        summary: "Not enough training history yet to project a load ratio.",
+    };
+    const profile = estimateHrProfile(input.series("resting_hr", CHRONIC_DAYS), input.series("max_hr", CHRONIC_DAYS));
+    if (!profile) {
+        return unknown;
+    }
+    if (input.series("resting_hr", CHRONIC_DAYS).length < MIN_CHRONIC_COVERAGE_DAYS) {
+        return unknown;
+    }
+    const byDay = dailyTrimp(input.activities(CHRONIC_DAYS + ACUTE_DAYS), profile);
+    const today = input.now.startOf("day");
+    const sumWindow = (fromDaysAgo, days) => {
+        let total = 0;
+        for (let offset = fromDaysAgo; offset < fromDaysAgo + days; offset += 1) {
+            const date = today.minus({ days: offset }).toISODate();
+            if (date) {
+                total += byDay.get(date) ?? 0;
+            }
+        }
+        return total;
+    };
+    const acute = sumWindow(0, ACUTE_DAYS);
+    const chronicTotal = sumWindow(0, CHRONIC_DAYS);
+    const chronicWeekly = chronicTotal / (CHRONIC_DAYS / ACUTE_DAYS);
+    if (chronicWeekly <= 0) {
+        return { ...unknown, acuteLoad: round(acute), chronicWeeklyLoad: 0 };
+    }
+    const currentRatio = round(acute / chronicWeekly);
+    // Slide the 28-day window forward seven days: drop the oldest week, add the
+    // week we are assuming.
+    const oldestWeek = sumWindow(CHRONIC_DAYS - ACUTE_DAYS, ACUTE_DAYS);
+    const projectedChronicTotal = chronicTotal - oldestWeek + acute;
+    const projectedChronicWeekly = projectedChronicTotal / (CHRONIC_DAYS / ACUTE_DAYS);
+    if (projectedChronicWeekly <= 0) {
+        return {
+            ...unknown,
+            currentRatio,
+            acuteLoad: round(acute),
+            chronicWeeklyLoad: round(chronicWeekly),
+        };
+    }
+    const projectedRatio = round(acute / projectedChronicWeekly);
+    const trajectory = projectedRatio > currentRatio + 0.05
+        ? "rising"
+        : projectedRatio < currentRatio - 0.05
+            ? "falling"
+            : "steady";
+    let verdict = "on_track";
+    if (projectedRatio > RATIO_HIGH) {
+        verdict = "spike_ahead";
+    }
+    else if (projectedRatio < RATIO_LOW) {
+        verdict = "detraining_ahead";
+    }
+    // What this week's load would have to be to sit on the edge of the band.
+    // Solved against the projected chronic window, which is the one the ratio
+    // will actually be measured against.
+    let weeklyLoadAdjustment = null;
+    if (verdict === "spike_ahead") {
+        weeklyLoadAdjustment = round(RATIO_HIGH * projectedChronicWeekly - acute, 0);
+    }
+    else if (verdict === "detraining_ahead") {
+        weeklyLoadAdjustment = round(RATIO_LOW * projectedChronicWeekly - acute, 0);
+    }
+    const provenance = "Load is TRIMP, computed here from duration and heart rate, and this is an extrapolation of the last seven days rather than a plan you have entered.";
+    const summary = verdict === "spike_ahead"
+        ? `Repeating this week puts your load ratio at ${projectedRatio}x, above the ${RATIO_HIGH}x mark where injury risk climbs. ${provenance}`
+        : verdict === "detraining_ahead"
+            ? `Repeating this week puts your load ratio at ${projectedRatio}x, below the ${RATIO_LOW}x mark where fitness starts to slip. ${provenance}`
+            : `Repeating this week keeps your load ratio near ${projectedRatio}x, inside the steady band. ${provenance}`;
+    return {
+        currentRatio,
+        projectedRatio,
+        trajectory,
+        verdict,
+        acuteLoad: round(acute, 0),
+        chronicWeeklyLoad: round(chronicWeekly, 0),
+        weeklyLoadAdjustment,
+        summary,
+    };
+}
+//# sourceMappingURL=forecast.js.map

package/dist/detect/forecast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forecast.js","sourceRoot":"","sources":["../../src/detect/forecast.ts"],"names":[],"mappings":"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"}

package/dist/detect/index.d.ts

@@ -0,0 +1,50 @@
+import { DateTime } from "luxon";
+import type { DetectorInput, Finding } from "./findings.js";
+export interface Coverage {
+    days: number;
+    ready: boolean;
+    /** Newest date with any measurement, or null for an empty store. */
+    throughDate: string | null;
+    /** Days between that and today. 0 when the record is current. */
+    staleDays: number;
+}
+export interface DetectionResult {
+    findings: Finding[];
+    coverage: Coverage;
+}
+/**
+ * Why `ready` is false, and the sentence to say about it.
+ *
+ * `ready` collapses two refusals that need opposite answers: COLD -- there is
+ * not enough history yet, wait -- and STALE -- there is plenty and it stops
+ * weeks ago, go and fetch. Each surface used to write that sentence itself, and
+ * only one of the four was taught the difference when `staleDays` was added.
+ * The three that were not printed the cold-start line at a 74-day store:
+ *
+ *     Still gathering data - 74 of the 14 days needed
+ *
+ * which is arithmetic nonsense, and worse, it is what a model repeats back to
+ * the user as "I don't have access to your data" -- while 598 measurements sit
+ * on disk. One description, read by every surface, is the only shape that stops
+ * the next surface from inheriting the same fault.
+ */
+export type CoverageState = "ready" | "stale" | "cold";
+export interface CoverageDescription {
+    state: CoverageState;
+    /** One sentence about the record itself. */
+    detail: string;
+    /** The single next action, or null when nothing needs doing. */
+    fix: string | null;
+}
+export declare function describeFindingsCoverage(coverage: Coverage): CoverageDescription;
+/** The only function here that touches the store. */
+export declare function buildDetectorInput(now?: DateTime): DetectorInput;
+/**
+ * Cold start is a first-class case, not an edge one. With no history every
+ * detector correctly returns null, and an empty array on its own is
+ * indistinguishable from a clean bill of health. `ready` is what lets a surface
+ * say "still gathering data" instead of implying everything is fine -- so
+ * surfaces read the flag, never the length of the array.
+ */
+export declare function runDetectors(input?: DetectorInput): DetectionResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/detect/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/detect/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AASjC,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAmB,MAAM,eAAe,CAAC;AAgC7E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,CAAC;IACrB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,mBAAmB,CAwBhF;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,QAA2B,GAAG,aAAa,CAgBlF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,aAAoC,GAAG,eAAe,CA6CzF"}