trainbud 0.5.0

package/dist/history/ingest.js

@@ -0,0 +1,347 @@
+import { DateTime } from "luxon";
+import { fetchBodyCompositionDay, fetchHeartRateDay, fetchSleepDay, fetchStressDay, fetchVo2MaxDay, } from "../garmin/daily.js";
+import { mapActivity } from "../garmin/daily.js";
+import { parseActivityLocalDateTime, parseIsoDate } from "../utils/helpers.js";
+import { logger } from "../utils/logger.js";
+import { GarminApiError } from "../garmin/types.js";
+import { writeFixture } from "./capture.js";
+import { appendRawPayload, listIngestedDates, markIngested, pruneRawPayloads, putActivities, putMetrics, } from "./store.js";
+// SECTION: Ingest
+//
+// The account is the thing at risk here, and there is no appeal process if
+// Garmin decides this looks like a scraper. So: one request in flight, a
+// deliberate delay between them, and a checkpoint written after every date so a
+// kill resumes where it stopped rather than starting the year again.
+/** Days that are never a final answer -- see NEVER_FINAL below. */
+const STALE_WINDOW_DAYS = 3;
+/** How long a stale-window day is trusted before it is worth asking again. */
+const STALE_RECHECK_SECONDS = 60 * 60;
+const DEFAULT_DAYS = 365;
+const DEFAULT_DELAY_MS = 1000;
+/**
+ * A watch has a purchase date, and asking Garmin about the months before it is
+ * spending requests against the account for nothing. Walking newest-first, a
+ * long unbroken run of empty days is the signal that the record has run out.
+ *
+ * 60 days rather than something tighter because a real person can stop wearing
+ * a watch for a while -- an injury, a holiday, a flat charger -- and the older
+ * history behind that gap is still worth having. Set to 0 to walk the whole
+ * window regardless.
+ */
+const DEFAULT_STOP_AFTER_EMPTY_DAYS = 60;
+/** The sources a full run covers. Exported so no caller keeps its own copy. */
+export const DEFAULT_SOURCES = [
+    "sleep",
+    "heart_rate",
+    "stress",
+    "vo2max",
+    "body_composition",
+    "activities",
+];
+/** Connect's page size for the activity list. */
+const ACTIVITY_PAGE_SIZE = 100;
+/** Backstop against paging forever if the window start is never reached. */
+const MAX_ACTIVITY_PAGES = 20;
+/** A GarminApiError carrying a 429, however it was wrapped on the way up. */
+function isRateLimit(error) {
+    if (error instanceof GarminApiError) {
+        return error.statusCode === 429;
+    }
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return message.includes("429") || message.includes("rate limit");
+    }
+    return false;
+}
+function activityStartDate(activity) {
+    return (parseActivityLocalDateTime(activity.startTimeLocal).toISODate() ??
+        activity.startTimeLocal.slice(0, 10));
+}
+function delay(ms, signal) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+/**
+ * A day inside the stale window is never a final answer: a sleep score
+ * finalizes hours after waking, VO2 max is recomputed after a qualifying
+ * activity, and Connect reports -2 for a day still in progress. Outside that
+ * window, any checkpoint is final -- including `empty`, which is what stops a
+ * backfill re-fetching a year of days the watch was not worn. `error` is always
+ * retried; it says nothing about the data.
+ */
+function shouldFetch(date, checkpoint, today, nowSeconds) {
+    if (!checkpoint) {
+        return true;
+    }
+    if (checkpoint.outcome === "error") {
+        return true;
+    }
+    const age = today.diff(DateTime.fromISO(date, { zone: today.zone }), "days").days;
+    const isNeverFinal = age < STALE_WINDOW_DAYS;
+    if (!isNeverFinal) {
+        return false;
+    }
+    return nowSeconds - checkpoint.fetchedAt >= STALE_RECHECK_SECONDS;
+}
+export function pendingWork(options = {}) {
+    const days = options.days ?? DEFAULT_DAYS;
+    const sources = options.sources ?? DEFAULT_SOURCES;
+    const now = options.now ?? DateTime.local();
+    const today = now.startOf("day");
+    const nowSeconds = now.toUnixInteger();
+    const work = [];
+    for (const source of sources) {
+        // Activities are paged, not addressed by date, so the whole window is one
+        // unit of work rather than one per day.
+        if (source === "activities") {
+            const date = today.toISODate();
+            if (date && shouldFetch(date, listIngestedDates(source).get(date), today, nowSeconds)) {
+                work.push({ date, source });
+            }
+            continue;
+        }
+        const checkpoints = listIngestedDates(source);
+        // Newest first: an interrupted backfill should leave the most recent
+        // history behind, not the oldest.
+        for (let offset = 0; offset < days; offset += 1) {
+            const date = today.minus({ days: offset }).toISODate();
+            if (!date) {
+                continue;
+            }
+            if (shouldFetch(date, checkpoints.get(date), today, nowSeconds)) {
+                work.push({ date, source });
+            }
+        }
+    }
+    return work;
+}
+function measured(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function collect(entries) {
+    const metrics = [];
+    for (const [kind, raw] of entries) {
+        const value = measured(raw);
+        if (value !== null) {
+            metrics.push({ kind, value });
+        }
+    }
+    return metrics;
+}
+async function fetchSource(source, client, date) {
+    switch (source) {
+        case "sleep": {
+            const { raw, mapped } = await fetchSleepDay(client, date);
+            return {
+                raw,
+                metrics: collect([
+                    ["sleep_seconds", mapped?.totalSleepSeconds],
+                    ["sleep_score", mapped?.sleepScore],
+                    ["hrv_overnight", mapped?.avgOvernightHrv],
+                    ["sleep_stress", mapped?.avgSleepStress],
+                ]),
+            };
+        }
+        case "heart_rate": {
+            const { raw, mapped } = await fetchHeartRateDay(client, date);
+            return {
+                raw,
+                metrics: collect([
+                    ["resting_hr", mapped?.restingHeartRate],
+                    ["max_hr", mapped?.maxHeartRate],
+                ]),
+            };
+        }
+        case "stress": {
+            const { raw, mapped } = await fetchStressDay(client, date);
+            return {
+                raw,
+                metrics: collect([
+                    ["stress_avg", mapped?.averageStress],
+                    ["stress_max", mapped?.maxStress],
+                ]),
+            };
+        }
+        case "vo2max": {
+            const { raw, mapped } = await fetchVo2MaxDay(client, date);
+            return {
+                raw,
+                metrics: collect([
+                    ["vo2max", mapped?.vo2Max],
+                    ["vo2max_cycling", mapped?.vo2MaxCycling],
+                ]),
+                measuredOn: mapped?.date,
+            };
+        }
+        case "body_composition": {
+            const { raw, mapped } = await fetchBodyCompositionDay(client, date);
+            // Several weigh-ins can share a date; the last one is the day's figure.
+            const entry = mapped?.at(-1);
+            return {
+                raw,
+                metrics: collect([
+                    ["weight_kg", entry?.weightKg],
+                    ["body_fat_pct", entry?.bodyFatPercent],
+                    ["muscle_mass_kg", entry?.muscleMassKg],
+                ]),
+            };
+        }
+        case "activities":
+            // Handled by ingestActivities, which pages rather than addressing a date.
+            return { raw: null, metrics: [] };
+    }
+}
+/**
+ * The activity list is paged newest-first, so the first activity older than the
+ * window means every remaining page is older still and there is nothing left to
+ * ask for.
+ */
+async function ingestActivities(client, windowStart, stampedAt, captureDir) {
+    let start = 0;
+    let stored = 0;
+    for (let page = 0; page < MAX_ACTIVITY_PAGES; page += 1) {
+        const activities = await client.getActivities(start, ACTIVITY_PAGE_SIZE);
+        if (activities.length === 0) {
+            break;
+        }
+        const mapped = activities.map(mapActivity);
+        putActivities(mapped, stampedAt);
+        stored += mapped.length;
+        if (captureDir) {
+            writeFixture(captureDir, "activities", `page-${page}`, activities);
+        }
+        const reachedWindowStart = mapped.some((activity) => activityStartDate(activity) < windowStart);
+        if (reachedWindowStart || activities.length < ACTIVITY_PAGE_SIZE) {
+            break;
+        }
+        start += ACTIVITY_PAGE_SIZE;
+    }
+    return stored;
+}
+export async function runIngest(client, options = {}) {
+    const delayMs = options.delayMs ?? DEFAULT_DELAY_MS;
+    const work = pendingWork(options);
+    // One clock for the whole run. Planning read `options.now` while the
+    // checkpoints were stamped from the wall clock, so a caller that supplied a
+    // clock got checkpoints the planner could not reason about.
+    const stampedAt = (options.now ?? DateTime.local()).toUnixInteger();
+    const stopAfterEmptyDays = options.stopAfterEmptyDays ?? DEFAULT_STOP_AFTER_EMPTY_DAYS;
+    const emptyRun = new Map();
+    const exhausted = new Set();
+    const result = {
+        fetched: 0,
+        skipped: 0,
+        errors: 0,
+        firstDate: null,
+        lastDate: null,
+    };
+    let done = 0;
+    for (const unit of work) {
+        if (options.signal?.aborted) {
+            result.skipped += work.length - done;
+            break;
+        }
+        // Deliberately not checkpointed. Skipping is not the same claim as "we
+        // asked and there was nothing", so a later run -- with a wider window, or
+        // with the limit disabled -- can still reach these days.
+        if (exhausted.has(unit.source)) {
+            result.skipped += 1;
+            done += 1;
+            continue;
+        }
+        let outcome;
+        try {
+            if (unit.source === "activities") {
+                const windowStart = (options.now ?? DateTime.local())
+                    .startOf("day")
+                    .minus({ days: options.days ?? DEFAULT_DAYS })
+                    .toISODate() ?? "";
+                const stored = await ingestActivities(client, windowStart, stampedAt, options.captureDir);
+                markIngested(unit.date, unit.source, stored > 0 ? "data" : "empty", stampedAt);
+                result.fetched += 1;
+                done += 1;
+                options.onProgress?.({
+                    ...unit,
+                    outcome: stored > 0 ? "data" : "empty",
+                    done,
+                    total: work.length,
+                });
+                if (done < work.length) {
+                    await delay(delayMs, options.signal);
+                }
+                continue;
+            }
+            // parseIsoDate, not new Date(): the bare constructor parses a date-only
+            // string as UTC midnight, and garmin-connect formats the Date it is given
+            // in local time. West of UTC that combination asks Garmin for the previous
+            // day and stores the answer under this one.
+            const { raw, metrics, measuredOn } = await fetchSource(unit.source, client, parseIsoDate(unit.date));
+            appendRawPayload(unit.date, unit.source, raw, stampedAt);
+            putMetrics(measuredOn ?? unit.date, metrics, stampedAt);
+            if (options.captureDir) {
+                writeFixture(options.captureDir, unit.source, unit.date, raw);
+            }
+            // A reading that belongs to another day is not a measurement for this
+            // one. Recording it as `data` would also defeat the empty-run stop, since
+            // every pre-purchase day would answer with today's reading forever.
+            const measuredHere = (measuredOn ?? unit.date) === unit.date;
+            outcome = metrics.length > 0 && measuredHere ? "data" : "empty";
+            result.fetched += 1;
+        }
+        catch (error) {
+            // One bad day must not end a year-long run -- but a rate limit is not one
+            // bad day, it is the upstream saying stop, and carrying on is how a
+            // 365-day backfill answered a 429 with seventeen hundred more requests.
+            // Each of those deepened the limit and none of them could have succeeded.
+            if (isRateLimit(error)) {
+                logger.warn({ error, ...unit, remaining: work.length - done }, "Garmin rate limited the ingest; stopping this run");
+                markIngested(unit.date, unit.source, "error", stampedAt);
+                result.errors += 1;
+                result.skipped += work.length - done - 1;
+                result.stoppedBy = "rate_limit";
+                break;
+            }
+            logger.warn({ error, ...unit }, "Ingest failed for one day");
+            outcome = "error";
+            result.errors += 1;
+        }
+        markIngested(unit.date, unit.source, outcome, stampedAt);
+        if (stopAfterEmptyDays > 0) {
+            const run = outcome === "empty" ? (emptyRun.get(unit.source) ?? 0) + 1 : 0;
+            emptyRun.set(unit.source, run);
+            if (run >= stopAfterEmptyDays) {
+                exhausted.add(unit.source);
+                logger.info({ source: unit.source, date: unit.date, emptyDays: run }, "Reached the start of the record for this source; skipping older days");
+            }
+        }
+        result.firstDate =
+            result.firstDate === null || unit.date < result.firstDate ? unit.date : result.firstDate;
+        result.lastDate =
+            result.lastDate === null || unit.date > result.lastDate ? unit.date : result.lastDate;
+        done += 1;
+        options.onProgress?.({ ...unit, outcome, done, total: work.length });
+        if (done < work.length) {
+            await delay(delayMs, options.signal);
+        }
+    }
+    // Every run appends a raw payload per day per source, so the archive grows
+    // with the number of runs and not with the amount of history. Bounding it
+    // here means the table is trimmed by the thing that fills it, rather than
+    // waiting for someone to notice the file.
+    if (result.fetched > 0) {
+        const pruned = pruneRawPayloads();
+        if (pruned.agedOut + pruned.supersededRevisions > 0) {
+            logger.debug({ ...pruned }, "Pruned the raw payload archive");
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=ingest.js.map

package/dist/history/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../src/history/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,0BAA0B,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,kBAAkB;AAClB,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,gFAAgF;AAChF,qEAAqE;AAErE,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,8EAA8E;AAC9E,MAAM,qBAAqB,GAAG,EAAE,GAAG,EAAE,CAAC;AAEtC,MAAM,YAAY,GAAG,GAAG,CAAC;AACzB,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;;;;;GASG;AACH,MAAM,6BAA6B,GAAG,EAAE,CAAC;AAEzC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,OAAO;IACP,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,kBAAkB;IAClB,YAAY;CACb,CAAC;AAEF,iDAAiD;AACjD,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,4EAA4E;AAC5E,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAqC9B,6EAA6E;AAC7E,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,UAAU,KAAK,GAAG,CAAC;IAClC,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAC5C,OAAO,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAOD,SAAS,iBAAiB,CAAC,QAAyB;IAClD,OAAO,CACL,0BAA0B,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE;QAC/D,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CACrC,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;YACrC,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAClB,IAAY,EACZ,UAAqE,EACrE,KAAe,EACf,UAAkB;IAElB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,UAAU,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC;IAClF,MAAM,YAAY,GAAG,GAAG,GAAG,iBAAiB,CAAC;IAE7C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,UAAU,GAAG,UAAU,CAAC,SAAS,IAAI,qBAAqB,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,UAAyB,EAAE;IACrD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,YAAY,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC;IACnD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,EAAE,CAAC;IAEvC,MAAM,IAAI,GAAiB,EAAE,CAAC;IAE9B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,0EAA0E;QAC1E,wCAAwC;QACxC,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC/B,IAAI,IAAI,IAAI,WAAW,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;gBACtF,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC9B,CAAC;YACD,SAAS;QACX,CAAC;QAED,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAE9C,qEAAqE;QACrE,kCAAkC;QAClC,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;YACvD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,SAAS;YACX,CAAC;YAED,IAAI,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;gBAChE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD,SAAS,QAAQ,CAAC,KAAgC;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5E,CAAC;AAED,SAAS,OAAO,CACd,OAAuD;IAEvD,MAAM,OAAO,GAA+C,EAAE,CAAC;IAE/D,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,MAAoB,EACpB,MAA6B,EAC7B,IAAU;IAEV,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC1D,OAAO;gBACL,GAAG;gBACH,OAAO,EAAE,OAAO,CAAC;oBACf,CAAC,eAAe,EAAE,MAAM,EAAE,iBAAiB,CAAC;oBAC5C,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC;oBACnC,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,CAAC;oBAC1C,CAAC,cAAc,EAAE,MAAM,EAAE,cAAc,CAAC;iBACzC,CAAC;aACH,CAAC;QACJ,CAAC;QACD,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC9D,OAAO;gBACL,GAAG;gBACH,OAAO,EAAE,OAAO,CAAC;oBACf,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,CAAC;oBACxC,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC;iBACjC,CAAC;aACH,CAAC;QACJ,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC3D,OAAO;gBACL,GAAG;gBACH,OAAO,EAAE,OAAO,CAAC;oBACf,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC;oBACrC,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC;iBAClC,CAAC;aACH,CAAC;QACJ,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC3D,OAAO;gBACL,GAAG;gBACH,OAAO,EAAE,OAAO,CAAC;oBACf,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;oBAC1B,CAAC,gBAAgB,EAAE,MAAM,EAAE,aAAa,CAAC;iBAC1C,CAAC;gBACF,UAAU,EAAE,MAAM,EAAE,IAAI;aACzB,CAAC;QACJ,CAAC;QACD,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACpE,wEAAwE;YACxE,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7B,OAAO;gBACL,GAAG;gBACH,OAAO,EAAE,OAAO,CAAC;oBACf,CAAC,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC;oBAC9B,CAAC,cAAc,EAAE,KAAK,EAAE,cAAc,CAAC;oBACvC,CAAC,gBAAgB,EAAE,KAAK,EAAE,YAAY,CAAC;iBACxC,CAAC;aACH,CAAC;QACJ,CAAC;QACD,KAAK,YAAY;YACf,0EAA0E;YAC1E,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,gBAAgB,CAC7B,MAA6B,EAC7B,WAAmB,EACnB,SAAiB,EACjB,UAAmB;IAEnB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,kBAAkB,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;QAEzE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM;QACR,CAAC;QAED,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC3C,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACjC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC;QAExB,IAAI,UAAU,EAAE,CAAC;YACf,YAAY,CAAC,UAAU,EAAE,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,UAAU,CAAC,CAAC;QACrE,CAAC;QAED,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI,CACpC,CAAC,QAAQ,EAAE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,GAAG,WAAW,CACxD,CAAC;QAEF,IAAI,kBAAkB,IAAI,UAAU,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;YACjE,MAAM;QACR,CAAC;QAED,KAAK,IAAI,kBAAkB,CAAC;IAC9B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAA6B,EAC7B,UAAyB,EAAE;IAE3B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAElC,qEAAqE;IACrE,4EAA4E;IAC5E,4DAA4D;IAC5D,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC;IACpE,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,6BAA6B,CAAC;IAEvF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgB,CAAC;IAE1C,MAAM,MAAM,GAAiB;QAC3B,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,IAAI;QACf,QAAQ,EAAE,IAAI;KACf,CAAC;IAEF,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAC5B,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACrC,MAAM;QACR,CAAC;QAED,uEAAuE;QACvE,0EAA0E;QAC1E,yDAAyD;QACzD,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/B,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YACpB,IAAI,IAAI,CAAC,CAAC;YACV,SAAS;QACX,CAAC;QAED,IAAI,OAAsB,CAAC;QAE3B,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;gBACjC,MAAM,WAAW,GACf,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;qBAC9B,OAAO,CAAC,KAAK,CAAC;qBACd,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;qBAC7C,SAAS,EAAE,IAAI,EAAE,CAAC;gBAEvB,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;gBAE1F,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;gBAC/E,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;gBACpB,IAAI,IAAI,CAAC,CAAC;gBACV,OAAO,CAAC,UAAU,EAAE,CAAC;oBACnB,GAAG,IAAI;oBACP,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO;oBACtC,IAAI;oBACJ,KAAK,EAAE,IAAI,CAAC,MAAM;iBACnB,CAAC,CAAC;gBAEH,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;oBACvB,MAAM,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;gBACvC,CAAC;gBACD,SAAS;YACX,CAAC;YAED,wEAAwE;YACxE,0EAA0E;YAC1E,2EAA2E;YAC3E,4CAA4C;YAC5C,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,WAAW,CACpD,IAAI,CAAC,MAAM,EACX,MAAM,EACN,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CACxB,CAAC;YAEF,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;YACzD,UAAU,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YAExD,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACvB,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAChE,CAAC;YAED,sEAAsE;YACtE,0EAA0E;YAC1E,oEAAoE;YACpE,MAAM,YAAY,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC;YAC7D,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;YAChE,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,0EAA0E;YAC1E,oEAAoE;YACpE,wEAAwE;YACxE,0EAA0E;YAC1E,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvB,MAAM,CAAC,IAAI,CACT,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,EACjD,mDAAmD,CACpD,CAAC;gBACF,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;gBACzD,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;gBACnB,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC;gBACzC,MAAM,CAAC,SAAS,GAAG,YAAY,CAAC;gBAChC,MAAM;YACR,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,2BAA2B,CAAC,CAAC;YAC7D,OAAO,GAAG,OAAO,CAAC;YAClB,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QACrB,CAAC;QAED,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QAEzD,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3E,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAE/B,IAAI,GAAG,IAAI,kBAAkB,EAAE,CAAC;gBAC9B,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC3B,MAAM,CAAC,IAAI,CACT,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,EACxD,sEAAsE,CACvE,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,CAAC,SAAS;YACd,MAAM,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;QAC3F,MAAM,CAAC,QAAQ;YACb,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;QAExF,IAAI,IAAI,CAAC,CAAC;QACV,OAAO,CAAC,UAAU,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAErE,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACvB,MAAM,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,0EAA0E;IAC1E,0EAA0E;IAC1E,0CAA0C;IAC1C,IAAI,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAClC,IAAI,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,mBAAmB,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,EAAE,gCAAgC,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/history/scheduler.d.ts

@@ -0,0 +1,20 @@
+export interface HistorySchedulerOptions {
+    intervalMs?: number;
+    run?: () => Promise<unknown>;
+}
+/**
+ * Returns its own stop function.
+ *
+ * Three properties this must keep:
+ *
+ * 1. The timer is unref()'d. A referenced interval holds the Node event loop
+ *    open, which is exactly the bug that made `npm test` hang until something
+ *    killed it (802d4d8) -- do not reintroduce it in a different shape.
+ * 2. Runs never overlap. A backfill can take an hour; queueing ticks behind it
+ *    would fire a burst of concurrent requests at Garmin the moment it
+ *    finished, which is the one thing the ingest pacing exists to prevent.
+ * 3. A failing run is logged and swallowed. The watch depends on this process
+ *    staying up, and a Garmin outage must not take the HTTP server with it.
+ */
+export declare function startHistoryScheduler(options?: HistorySchedulerOptions): () => void;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/history/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/history/scheduler.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM,IAAI,CA+BvF"}

package/dist/history/scheduler.js

@@ -0,0 +1,54 @@
+import { withGarminClient } from "../garmin/client.js";
+import { logger } from "../utils/logger.js";
+import { runIngest } from "./ingest.js";
+// SECTION: History scheduler
+//
+// There is no daemon and the machine is not always on, but Garmin retains the
+// history, so any gap is recoverable. Catching up on start and then ticking
+// while the process lives is enough to keep a year current without asking the
+// user to run anything or install a service.
+const DEFAULT_INTERVAL_MS = 60 * 60 * 1000;
+async function catchUp() {
+    return withGarminClient(async (client) => runIngest(client));
+}
+/**
+ * Returns its own stop function.
+ *
+ * Three properties this must keep:
+ *
+ * 1. The timer is unref()'d. A referenced interval holds the Node event loop
+ *    open, which is exactly the bug that made `npm test` hang until something
+ *    killed it (802d4d8) -- do not reintroduce it in a different shape.
+ * 2. Runs never overlap. A backfill can take an hour; queueing ticks behind it
+ *    would fire a burst of concurrent requests at Garmin the moment it
+ *    finished, which is the one thing the ingest pacing exists to prevent.
+ * 3. A failing run is logged and swallowed. The watch depends on this process
+ *    staying up, and a Garmin outage must not take the HTTP server with it.
+ */
+export function startHistoryScheduler(options = {}) {
+    const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const run = options.run ?? catchUp;
+    let running = false;
+    let stopped = false;
+    const tick = () => {
+        if (stopped || running) {
+            return;
+        }
+        running = true;
+        void run()
+            .catch((error) => {
+            logger.warn({ error }, "History catch-up failed");
+        })
+            .finally(() => {
+            running = false;
+        });
+    };
+    tick();
+    const timer = setInterval(tick, intervalMs);
+    timer.unref();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/history/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/history/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAqB,MAAM,aAAa,CAAC;AAE3D,6BAA6B;AAC7B,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,6CAA6C;AAE7C,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAO3C,KAAK,UAAU,OAAO;IACpB,OAAO,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAmC,EAAE;IACzE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC;IAEnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;YACvB,OAAO;QACT,CAAC;QAED,OAAO,GAAG,IAAI,CAAC;QACf,KAAK,GAAG,EAAE;aACP,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,yBAAyB,CAAC,CAAC;QACpD,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IAEF,IAAI,EAAE,CAAC;IAEP,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC5C,KAAK,CAAC,KAAK,EAAE,CAAC;IAEd,OAAO,GAAG,EAAE;QACV,OAAO,GAAG,IAAI,CAAC;QACf,aAAa,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/history/schema.d.ts

@@ -0,0 +1,41 @@
+/**
+ * One row per measurement. Sources that report several numbers for a day write
+ * several rows.
+ */
+export type MetricKind = "sleep_seconds" | "sleep_score" | "hrv_overnight" | "sleep_stress" | "resting_hr" | "max_hr" | "stress_avg" | "stress_max" | "vo2max" | "vo2max_cycling" | "weight_kg" | "body_fat_pct" | "muscle_mass_kg";
+/** One Garmin endpoint family, fetched a day at a time. */
+export type IngestSource = "sleep" | "heart_rate" | "stress" | "vo2max" | "body_composition" | "activities";
+/**
+ * `data` -- the day was fetched and something was measured.
+ * `empty` -- the day was fetched and Garmin has nothing, which is a final
+ *            answer for any date outside the stale window: the watch was not
+ *            worn and never will have been.
+ * `error` -- the request failed. Retried on the next run.
+ */
+export type IngestOutcome = "data" | "empty" | "error";
+/**
+ * What the user tells us that Garmin has no idea about. This is the whole
+ * differentiator: Connect holds the measurements and no notion of who is being
+ * measured or what they are training for.
+ */
+export type ContextKind = "goal" | "race" | "injury" | "note";
+/** Rated 1-10, one per day per kind. */
+export type SubjectiveKind = "rpe" | "soreness" | "mood";
+export declare const CONTEXT_KINDS: ContextKind[];
+export declare const SUBJECTIVE_KINDS: SubjectiveKind[];
+/**
+ * `daily_metric.value` is NOT NULL and a row exists only for a real
+ * measurement, so "is there a row" answers "was this measured". The different
+ * question -- "have we ever asked Garmin about this day" -- is what ingest_day
+ * answers, and keeping the two apart is what stops a backfill from re-fetching
+ * a year of days the user did not wear the watch.
+ *
+ * raw_payload is append-only. Garmin restates data (a sleep score finalizes
+ * hours after waking, VO2 max is recomputed after a qualifying activity), and
+ * an archive that overwrote would hide exactly the revision worth seeing. It is
+ * also the insurance against a mapping bug: this project has twice read a field
+ * Connect does not send, and re-deriving from the archive beats re-fetching a
+ * year against an unofficial API.
+ */
+export declare const HISTORY_SCHEMA = "\n  CREATE TABLE IF NOT EXISTS daily_metric (\n    date       TEXT    NOT NULL,\n    kind       TEXT    NOT NULL,\n    value      REAL    NOT NULL,\n    fetched_at INTEGER NOT NULL,\n    PRIMARY KEY (date, kind)\n  );\n\n  CREATE TABLE IF NOT EXISTS raw_payload (\n    id         INTEGER PRIMARY KEY AUTOINCREMENT,\n    date       TEXT    NOT NULL,\n    source     TEXT    NOT NULL,\n    fetched_at INTEGER NOT NULL,\n    json       TEXT    NOT NULL\n  );\n\n  CREATE INDEX IF NOT EXISTS raw_payload_date_source\n    ON raw_payload (date, source, fetched_at);\n\n  CREATE TABLE IF NOT EXISTS ingest_day (\n    date       TEXT    NOT NULL,\n    source     TEXT    NOT NULL,\n    fetched_at INTEGER NOT NULL,\n    outcome    TEXT    NOT NULL,\n    PRIMARY KEY (date, source)\n  );\n\n  CREATE TABLE IF NOT EXISTS activity (\n    activity_id      INTEGER PRIMARY KEY,\n    date             TEXT    NOT NULL,\n    start_time_local TEXT    NOT NULL,\n    name             TEXT    NOT NULL,\n    type             TEXT    NOT NULL,\n    distance_m       REAL,\n    duration_s       REAL,\n    avg_hr           REAL,\n    max_hr           REAL,\n    elevation_gain_m REAL,\n    calories         REAL,\n    avg_speed_mps    REAL,\n    fetched_at       INTEGER NOT NULL\n  );\n\n  CREATE INDEX IF NOT EXISTS activity_date ON activity (date);\n\n  CREATE TABLE IF NOT EXISTS context_entry (\n    id             INTEGER PRIMARY KEY AUTOINCREMENT,\n    kind           TEXT    NOT NULL,\n    text           TEXT    NOT NULL,\n    effective_from TEXT    NOT NULL,\n    effective_to   TEXT,\n    created_at     INTEGER NOT NULL\n  );\n\n  CREATE INDEX IF NOT EXISTS context_entry_range\n    ON context_entry (effective_from, effective_to);\n\n  CREATE TABLE IF NOT EXISTS subjective (\n    date       TEXT    NOT NULL,\n    kind       TEXT    NOT NULL,\n    value      REAL    NOT NULL,\n    note       TEXT,\n    created_at INTEGER NOT NULL,\n    PRIMARY KEY (date, kind)\n  );\n";
+//# sourceMappingURL=schema.d.ts.map

package/dist/history/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/history/schema.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,eAAe,GACf,aAAa,GACb,eAAe,GACf,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,gBAAgB,CAAC;AAErB,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,kBAAkB,GAClB,YAAY,CAAC;AAEjB;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9D,wCAAwC;AACxC,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzD,eAAO,MAAM,aAAa,EAAE,WAAW,EAAuC,CAAC;AAC/E,eAAO,MAAM,gBAAgB,EAAE,cAAc,EAAgC,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,i7DAkE1B,CAAC"}

package/dist/history/schema.js

@@ -0,0 +1,91 @@
+// SECTION: History schema
+//
+// TrainBud's own copy of the Garmin record. Garmin remains the system of truth
+// -- anything here can be re-fetched -- but nothing can be *asked* of data that
+// was never kept, and the tool cache is TTL-keyed and deletes its own rows.
+// Without this, every answer is derived from one day's numbers, which is the
+// whole reason the app could only ever repeat what Connect already showed.
+export const CONTEXT_KINDS = ["goal", "race", "injury", "note"];
+export const SUBJECTIVE_KINDS = ["rpe", "soreness", "mood"];
+/**
+ * `daily_metric.value` is NOT NULL and a row exists only for a real
+ * measurement, so "is there a row" answers "was this measured". The different
+ * question -- "have we ever asked Garmin about this day" -- is what ingest_day
+ * answers, and keeping the two apart is what stops a backfill from re-fetching
+ * a year of days the user did not wear the watch.
+ *
+ * raw_payload is append-only. Garmin restates data (a sleep score finalizes
+ * hours after waking, VO2 max is recomputed after a qualifying activity), and
+ * an archive that overwrote would hide exactly the revision worth seeing. It is
+ * also the insurance against a mapping bug: this project has twice read a field
+ * Connect does not send, and re-deriving from the archive beats re-fetching a
+ * year against an unofficial API.
+ */
+export const HISTORY_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS daily_metric (
+    date       TEXT    NOT NULL,
+    kind       TEXT    NOT NULL,
+    value      REAL    NOT NULL,
+    fetched_at INTEGER NOT NULL,
+    PRIMARY KEY (date, kind)
+  );
+
+  CREATE TABLE IF NOT EXISTS raw_payload (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    date       TEXT    NOT NULL,
+    source     TEXT    NOT NULL,
+    fetched_at INTEGER NOT NULL,
+    json       TEXT    NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS raw_payload_date_source
+    ON raw_payload (date, source, fetched_at);
+
+  CREATE TABLE IF NOT EXISTS ingest_day (
+    date       TEXT    NOT NULL,
+    source     TEXT    NOT NULL,
+    fetched_at INTEGER NOT NULL,
+    outcome    TEXT    NOT NULL,
+    PRIMARY KEY (date, source)
+  );
+
+  CREATE TABLE IF NOT EXISTS activity (
+    activity_id      INTEGER PRIMARY KEY,
+    date             TEXT    NOT NULL,
+    start_time_local TEXT    NOT NULL,
+    name             TEXT    NOT NULL,
+    type             TEXT    NOT NULL,
+    distance_m       REAL,
+    duration_s       REAL,
+    avg_hr           REAL,
+    max_hr           REAL,
+    elevation_gain_m REAL,
+    calories         REAL,
+    avg_speed_mps    REAL,
+    fetched_at       INTEGER NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS activity_date ON activity (date);
+
+  CREATE TABLE IF NOT EXISTS context_entry (
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    kind           TEXT    NOT NULL,
+    text           TEXT    NOT NULL,
+    effective_from TEXT    NOT NULL,
+    effective_to   TEXT,
+    created_at     INTEGER NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS context_entry_range
+    ON context_entry (effective_from, effective_to);
+
+  CREATE TABLE IF NOT EXISTS subjective (
+    date       TEXT    NOT NULL,
+    kind       TEXT    NOT NULL,
+    value      REAL    NOT NULL,
+    note       TEXT,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (date, kind)
+  );
+`;
+//# sourceMappingURL=schema.js.map

package/dist/history/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/history/schema.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAiD3E,MAAM,CAAC,MAAM,aAAa,GAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkE7B,CAAC"}