catence 0.2.0-beta.9 → 0.2.0

package/dist/elt/normalization/normalizers.js

@@ -63,7 +63,8 @@ function swimSourceLabel(payload) {
 function datePart(value) {
     if (!value)
         return null;
-    const match = value.match(/^\d{4}-\d{2}-\d{2}/);
+    const s = typeof value === 'string' ? value : value.toISOString();
+    const match = s.match(/^\d{4}-\d{2}-\d{2}/);
     return match?.[0] ?? null;
 }
 function providerActivityId(provider, remoteId) {
@@ -143,6 +144,8 @@ function snake(value) {
     return value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase();
 }
 function timestamp(value) {
+    if (value instanceof Date)
+        return value.toISOString();
     if (typeof value === 'string' && value.length >= 10)
         return value;
     if (typeof value !== 'number' || !Number.isFinite(value))
@@ -163,30 +166,69 @@ async function upsertDailyMetric(database, provider, metricDate, metricName, val
      ON CONFLICT (provider, metric_date, metric_name) DO UPDATE SET value_number = excluded.value_number, value_text = excluded.value_text,
        unit = excluded.unit, raw_object_hash = excluded.raw_object_hash`, { provider, metricDate, metricName, valueNumber, valueText, unit, rawHash });
 }
+/**
+ * Garmin's nutrition food log keeps its actuals under dailyNutritionContent
+ * (a per-day rolled-up object), while meal definitions and hydration endpoints
+ * share the same source entity type. Flat keys are kept for providers that
+ * return them directly.
+ */
 function nutritionFields(payload) {
+    const content = object(payload.dailyNutritionContent);
     return {
-        energyKcal: firstNumber(payload, ['kcalConsumed', 'calories', 'totalCalories', 'energyKcal']),
-        carbohydratesG: firstNumber(payload, ['carbohydrates', 'carbs', 'totalCarbs', 'carbohydrateGrams']),
-        proteinG: firstNumber(payload, ['protein', 'totalProtein', 'proteinGrams']),
-        fatG: firstNumber(payload, ['fatTotal', 'fat', 'totalFat', 'fatGrams']),
-        hydrationMl: firstNumber(payload, ['hydrationVolume', 'hydration', 'waterMl', 'totalWater']),
+        energyKcal: firstNumber(payload, ['kcalConsumed', 'calories', 'totalCalories', 'energyKcal']) ?? firstNumber(content, ['calories', 'energyKcal', 'totalCalories']),
+        carbohydratesG: firstNumber(payload, ['carbohydrates', 'carbs', 'totalCarbs', 'carbohydrateGrams']) ?? firstNumber(content, ['carbohydrates', 'carbs']),
+        proteinG: firstNumber(payload, ['protein', 'totalProtein', 'proteinGrams']) ?? firstNumber(content, ['protein']),
+        fatG: firstNumber(payload, ['fatTotal', 'fat', 'totalFat', 'fatGrams']) ?? firstNumber(content, ['fat', 'fatTotal']),
+        hydrationMl: firstNumber(payload, ['hydrationVolume', 'hydration', 'waterMl', 'totalWater', 'valueInML', 'dailyAverageinML']),
     };
 }
+/**
+ * Garmin food-log items live under mealDetails[].foods[]. Each food carries the
+ * day's nutrition_date, so a meal label is folded onto the item to avoid losing
+ * it. Flat arrays are kept for providers that return items directly.
+ */
 function nutritionItems(payload) {
-    const candidates = ['foodItems', 'items', 'entries', 'foodLogEntries', 'meals'];
-    for (const key of candidates) {
+    const items = [];
+    const mealDetails = payload.mealDetails;
+    if (Array.isArray(mealDetails)) {
+        for (const detail of mealDetails) {
+            const mealDetail = object(detail);
+            const mealName = firstString(object(mealDetail.meal), ['mealName']) ?? firstString(mealDetail, ['mealName']);
+            const foods = mealDetail.foods;
+            if (Array.isArray(foods)) {
+                for (const food of foods) {
+                    const item = object(food);
+                    if (Object.keys(item).length === 0)
+                        continue;
+                    items.push(mealName ? { ...item, mealName } : item);
+                }
+            }
+            else if (Object.keys(mealDetail).length > 0 && firstString(mealDetail, ['foodName', 'name', 'description']) !== null) {
+                items.push(mealName ? { ...mealDetail, mealName } : mealDetail);
+            }
+        }
+        if (items.length > 0)
+            return items;
+    }
+    for (const key of ['foodItems', 'items', 'entries', 'foodLogEntries', 'meals']) {
         const value = payload[key];
         if (Array.isArray(value))
             return value.map(object).filter((item) => Object.keys(item).length > 0);
     }
     return [];
 }
+/** True when a payload contributes real nutrition facts rather than meal definitions or hydration-only bookkeeping. */
+function hasNutritionContent(payload) {
+    const fields = nutritionFields(payload);
+    return fields.energyKcal !== null || fields.carbohydratesG !== null || fields.proteinG !== null || fields.fatG !== null
+        || fields.hydrationMl !== null || nutritionItems(payload).length > 0;
+}
 export async function importSourceEntity(database, entity) {
     const payload = object(entity.payload);
     const rawHash = entity.rawObjectHash;
     await database.run(`INSERT INTO source_entities
       (provider, entity_type, remote_id, parent_remote_id, occurred_on, source_updated_at, raw_object_hash, payload_json, extension_json)
-      VALUES ($provider, $entityType, $remoteId, $parentRemoteId, $occurredOn, $sourceUpdatedAt, $rawHash, $payload, $extension)
+      VALUES ($provider::VARCHAR, $entityType::VARCHAR, $remoteId::VARCHAR, $parentRemoteId::VARCHAR, $occurredOn::TIMESTAMPTZ, $sourceUpdatedAt::TIMESTAMPTZ, $rawHash::VARCHAR, $payload::JSON, $extension::JSON)
       ON CONFLICT (provider, entity_type, remote_id) DO UPDATE SET
         parent_remote_id = excluded.parent_remote_id, occurred_on = excluded.occurred_on,
         source_updated_at = excluded.source_updated_at, raw_object_hash = excluded.raw_object_hash,
@@ -197,7 +239,7 @@ export async function importSourceEntity(database, entity) {
     });
     await database.run(`INSERT INTO domain_entities
       (provider, entity_type, remote_id, parent_remote_id, occurred_on, payload_json, extension_json, raw_object_hash)
-      VALUES ($provider, $entityType, $remoteId, $parentRemoteId, $occurredOn, $payload, $extension, $rawHash)
+      VALUES ($provider::VARCHAR, $entityType::VARCHAR, $remoteId::VARCHAR, $parentRemoteId::VARCHAR, $occurredOn::TIMESTAMPTZ, $payload::JSON, $extension::JSON, $rawHash::VARCHAR)
       ON CONFLICT (provider, entity_type, remote_id) DO UPDATE SET
         parent_remote_id = excluded.parent_remote_id, occurred_on = excluded.occurred_on,
         payload_json = excluded.payload_json, extension_json = excluded.extension_json, raw_object_hash = excluded.raw_object_hash`, {
@@ -211,6 +253,7 @@ export async function importSourceEntity(database, entity) {
     }
     if (entity.entityType === 'activity') {
         await importActivity(database, entity.provider, entity.remoteId, payload, rawHash);
+        await importActivityDecoupling(database, entity.provider, entity.remoteId, payload, rawHash);
         if (entity.provider === 'intervals')
             await importIntervalsAutoSwimSets(database, entity.remoteId, payload, rawHash);
         if (entity.provider === 'garmin') {
@@ -223,6 +266,9 @@ export async function importSourceEntity(database, entity) {
     if (entity.provider === 'garmin' && ['activity_detail', 'activity_interval', 'activity_exercise_set'].includes(entity.entityType)) {
         await importGarminExplicitSwimLengths(database, entity.parentRemoteId, entity.entityType, payload, rawHash);
     }
+    if (entity.provider === 'garmin' && entity.entityType === 'activity_swim_lengths') {
+        await importGarminFitSwimLengths(database, entity.parentRemoteId, payload, rawHash);
+    }
     if (entity.entityType === 'wellness' || entity.entityType === 'daily_health')
         await importDailyMetrics(database, entity.provider, entity.remoteId, entity.occurredOn, payload, rawHash);
     if (entity.entityType === 'nutrition_day' || entity.entityType === 'nutrition_log')
@@ -245,6 +291,8 @@ export async function importSourceEntity(database, entity) {
         await importHealthSession(database, entity.remoteId, entity.occurredOn, 'daily_event', payload, rawHash);
     if (entity.provider === 'garmin' && entity.entityType === 'activity_power_best')
         await importActivityPowerBest(database, entity.parentRemoteId, payload, rawHash);
+    if (entity.provider === 'garmin' && entity.entityType === 'course')
+        await importGarminCourse(database, entity.remoteId, payload, rawHash);
 }
 async function importActivity(database, provider, remoteId, payload, rawHash) {
     const fields = activityFields(provider, payload);
@@ -372,7 +420,7 @@ function nested(payload, key) {
     return object(payload[key]);
 }
 function metricObservedAt(occurredOn, payload) {
-    return firstTimestamp(payload, ['timestamp', 'timestampLocal', 'calendarDate', 'date']) ?? (occurredOn ? `${occurredOn}T00:00:00Z` : null);
+    return firstTimestamp(payload, ['timestamp', 'timestampLocal', 'calendarDate', 'date']) ?? (occurredOn ? `${datePart(occurredOn)}T00:00:00Z` : null);
 }
 async function importGarminActivityPerformance(database, remoteId, payload, rawHash) {
     const fields = activityFields('garmin', payload);
@@ -474,6 +522,99 @@ async function importGarminNumericSeries(database, entityType, remoteId, occurre
         });
     }
 }
+const DECOUPLING_METRICS = [
+    { metric: 'aerobic_decoupling_pct', unit: 'pct', keys: ['decoupling', 'aerobicDecoupling', 'icu_decoupling', 'paHrDecoupling', 'pwHrDecoupling', 'aerobic_decoupling'] },
+    { metric: 'grade_adjusted_pace_s_per_km', unit: 's_per_km', keys: ['gap', 'gradeAdjustedPace', 'icu_gap', 'grade_adjusted_pace'] },
+];
+/** Containers searched for provider-supplied decoupling/GAP: the payload itself,
+ * its common nested analysis/metrics objects, and the stored metrics_json. */
+function decouplingContainers(payload) {
+    const containers = [payload];
+    for (const key of ['analysis', 'data', 'metrics', 'icuAnalysis', 'summaries']) {
+        const nested = payload[key];
+        if (nested !== null && typeof nested === 'object' && !Array.isArray(nested))
+            containers.push(nested);
+    }
+    const metricsJson = payload.metrics_json;
+    if (metricsJson !== undefined && metricsJson !== null)
+        containers.push(objectFromJson(metricsJson));
+    return containers;
+}
+/** A3 (persistence): persist provider-supplied aerobic decoupling (Pa:Hr) and
+ * grade-adjusted pace from an activity payload so they are queryable historically
+ * instead of only inside one activity's raw metrics_json. Provider values are
+ * stored as source_type 'provider' and are authoritative. Locally derived values
+ * (deriveDecoding/deriveGap) are a separate, still-derived path. */
+async function importActivityDecoupling(database, provider, remoteId, payload, rawHash) {
+    const activitySourceId = providerActivityId(provider, remoteId);
+    const fields = activityFields(provider, payload);
+    const containers = decouplingContainers(payload);
+    for (const spec of DECOUPLING_METRICS) {
+        let value = null;
+        for (const container of containers) {
+            const found = firstNumber(container, spec.keys);
+            if (found !== null) {
+                value = found;
+                break;
+            }
+        }
+        if (value === null)
+            continue;
+        await database.run(`INSERT INTO activity_decoupling_facts (provider, activity_source_id, sport, started_at_utc, metric, value_number, unit, source_type, caveats_json, raw_object_hash)
+       VALUES ($provider, $activitySourceId, $sport, try_cast($startedAtUtc AS TIMESTAMPTZ), $metric, $value, $unit, 'provider', $caveats, $rawHash)
+       ON CONFLICT (provider, activity_source_id, metric) DO UPDATE SET
+         sport = excluded.sport, started_at_utc = excluded.started_at_utc, value_number = excluded.value_number,
+         unit = excluded.unit, source_type = excluded.source_type, caveats_json = excluded.caveats_json, raw_object_hash = excluded.raw_object_hash`, { provider, activitySourceId, sport: fields.sport, startedAtUtc: fields.startAtUtc, metric: spec.metric, value, unit: spec.unit, caveats: json({}), rawHash });
+    }
+}
+/** Pull a course's ordered geometry samples, tolerating the several shapes a
+ * Garmin course payload may use (a flat ``geoPoints`` array on the live course
+ * endpoint, legacy ``coursePoints``, or points nested under a geo/route object).
+ * Returns an empty list when no geometry is present. */
+function courseGeometryPoints(payload) {
+    const candidates = [payload.geoPoints, payload.coursePoints, payload.geo, payload.points, payload.geometry, payload.locations, payload.geoRoute];
+    for (const candidate of candidates) {
+        if (Array.isArray(candidate))
+            return objectArray(candidate);
+        if (candidate !== null && typeof candidate === 'object' && !Array.isArray(candidate)) {
+            const obj = candidate;
+            for (const key of ['coursePoints', 'points', 'locations', 'coursePoint']) {
+                if (Array.isArray(obj[key]))
+                    return objectArray(obj[key]);
+            }
+        }
+    }
+    return [];
+}
+/** A4: normalize Garmin course geometry into course_geometry so a race's
+ * elevation/grade profile can be resolved and diffed. The raw payload is also
+ * stored by importSourceEntity, so this only fans the points into rows. Live
+ * Garmin courses carry a ``geoPoints`` array (one row per sample); inserts are
+ * batched because a full course is roughly two thousand points. */
+async function importGarminCourse(database, remoteId, payload, rawHash) {
+    const points = courseGeometryPoints(payload);
+    const CHUNK = 500;
+    for (let offset = 0; offset < points.length; offset += CHUNK) {
+        const chunk = points.slice(offset, offset + CHUNK);
+        const values = { courseId: remoteId, rawHash };
+        const rows = [];
+        for (let i = 0; i < chunk.length; i++) {
+            const point = chunk[i];
+            const seq = offset + i;
+            values[`seq${i}`] = seq;
+            values[`lat${i}`] = firstNumber(point, ['latitude', 'lat']);
+            values[`lon${i}`] = firstNumber(point, ['longitude', 'lon', 'lng']);
+            values[`alt${i}`] = firstNumber(point, ['elevation', 'altitude', 'altitudeMeters', 'ele']);
+            values[`dist${i}`] = firstNumber(point, ['distance', 'distanceMeters', 'distance_m']);
+            rows.push(`($courseId, $seq${i}, $lat${i}, $lon${i}, $alt${i}, $dist${i}, $rawHash)`);
+        }
+        await database.run(`INSERT INTO course_geometry (course_id, seq, lat, lon, altitude_m, distance_m, raw_object_hash)
+       VALUES ${rows.join(', ')}
+       ON CONFLICT (course_id, seq) DO UPDATE SET
+         lat = excluded.lat, lon = excluded.lon, altitude_m = excluded.altitude_m,
+         distance_m = excluded.distance_m, raw_object_hash = excluded.raw_object_hash`, values);
+    }
+}
 async function importGarminTrainingStatus(database, remoteId, occurredOn, payload, rawHash) {
     const statusMap = nested(nested(payload, 'mostRecentTrainingStatus'), 'latestTrainingStatusData');
     const balanceMap = nested(nested(payload, 'mostRecentTrainingLoadBalance'), 'metricsTrainingLoadBalanceDTOMap');
@@ -668,6 +809,46 @@ async function importGarminExplicitSwimLengths(database, parentRemoteId, entityT
         }
     }
 }
+async function importGarminFitSwimLengths(database, parentRemoteId, payload, rawHash) {
+    if (!parentRemoteId)
+        return;
+    const activitySourceId = providerActivityId('garmin', parentRemoteId);
+    const lengths = objectArray(payload.lengths);
+    if (lengths.length === 0)
+        return;
+    const source = 'garmin_fit_length';
+    await database.run('DELETE FROM swim_lengths WHERE activity_source_id = $activitySourceId AND source = $source', { activitySourceId, source });
+    const summaryPoolLengthM = await activityPoolLengthM(database, activitySourceId);
+    for (const [offset, length] of lengths.entries()) {
+        const durationS = firstNumber(length, ['durationS', 'duration', 'durationSeconds', 'elapsedDuration']);
+        if (durationS === null)
+            continue;
+        const sourceLabel = swimSourceLabel(length);
+        const isRest = firstBoolean(length, ['isRest', 'rest']) ?? Boolean(sourceLabel && /rest|idle|pause/.test(sourceLabel));
+        const lengthIndex = Math.round(firstNumber(length, ['lengthIndex', 'messageIndex', 'lengthNumber', 'index']) ?? offset);
+        await database.run(`INSERT INTO swim_lengths
+        (activity_source_id, source, length_index, lap_index, pool_length_m, start_time, duration_s, active_duration_s, distance_m, stroke_count, stroke_rate, swolf, avg_hr, max_hr, is_rest, confidence, metrics_json, raw_object_hash)
+       VALUES ($activitySourceId, $source, $lengthIndex, $lapIndex, $poolLengthM, $startTime, $durationS, $activeDurationS, $distanceM, $strokeCount, $strokeRate, $swolf, $avgHr, $maxHr, $isRest, 'provider_supplied', $metrics, $rawHash)
+       ON CONFLICT (activity_source_id, source, length_index) DO UPDATE SET
+         lap_index = excluded.lap_index, pool_length_m = excluded.pool_length_m, start_time = excluded.start_time,
+         duration_s = excluded.duration_s, active_duration_s = excluded.active_duration_s, distance_m = excluded.distance_m,
+         stroke_count = excluded.stroke_count, stroke_rate = excluded.stroke_rate, swolf = excluded.swolf,
+         avg_hr = excluded.avg_hr, max_hr = excluded.max_hr, is_rest = excluded.is_rest,
+         confidence = excluded.confidence, metrics_json = excluded.metrics_json, raw_object_hash = excluded.raw_object_hash`, {
+            activitySourceId, source, lengthIndex,
+            lapIndex: firstNumber(length, ['lapIndex', 'lapNumber']), poolLengthM: garminPoolLengthM(length) ?? summaryPoolLengthM,
+            startTime: timestamp(length.startTime ?? length.startTimestamp ?? length.timestamp), durationS,
+            activeDurationS: firstNumber(length, ['activeDurationS', 'activeDuration', 'movingDuration']),
+            distanceM: firstNumber(length, ['distanceM', 'distance']),
+            strokeCount: firstNumber(length, ['strokeCount', 'strokes', 'total_strokes']),
+            strokeRate: firstNumber(length, ['strokeRate', 'averageStrokeRate', 'avg_swimming_cadence', 'avg_cadence', 'cadence']),
+            swolf: firstNumber(length, ['swolf', 'avg_swolf']),
+            avgHr: firstNumber(length, ['avgHr', 'averageHR', 'avg_heart_rate']),
+            maxHr: firstNumber(length, ['maxHr', 'maxHR', 'max_heart_rate']),
+            isRest, metrics: json(length), rawHash,
+        });
+    }
+}
 async function addActivityQualityFlag(database, activitySourceId, code, severity, details, rawHash) {
     await database.run(`INSERT INTO activity_quality_flags (activity_source_id, flag_code, severity, details_json, raw_object_hash)
      VALUES ($activitySourceId, $code, $severity, $details, $rawHash)
@@ -791,18 +972,29 @@ async function importNutrition(database, provider, date, remoteId, payload, rawH
     const nutritionDate = datePart(date) ?? datePart(firstString(payload, ['id', 'date', 'calendarDate'])) ?? null;
     if (!nutritionDate)
         return;
+    if (!hasNutritionContent(payload))
+        return;
     const fields = nutritionFields(payload);
     await database.run(`INSERT INTO nutrition_days
       (provider, nutrition_date, energy_kcal, carbohydrates_g, protein_g, fat_g, hydration_ml, metrics_json, raw_object_hash)
-      VALUES ($provider, $nutritionDate, $energyKcal, $carbohydratesG, $proteinG, $fatG, $hydrationMl, $metrics, $rawHash)
-      ON CONFLICT (provider, nutrition_date) DO UPDATE SET energy_kcal = excluded.energy_kcal, carbohydrates_g = excluded.carbohydrates_g,
-       protein_g = excluded.protein_g, fat_g = excluded.fat_g, hydration_ml = excluded.hydration_ml, metrics_json = excluded.metrics_json, raw_object_hash = excluded.raw_object_hash`, { provider, nutritionDate, ...fields, metrics: json(payload), rawHash });
+      VALUES ($provider::VARCHAR, $nutritionDate::DATE, $energyKcal::DOUBLE, $carbohydratesG::DOUBLE, $proteinG::DOUBLE, $fatG::DOUBLE, $hydrationMl::DOUBLE, $metrics::JSON, $rawHash::VARCHAR)
+      ON CONFLICT (provider, nutrition_date) DO UPDATE SET
+        energy_kcal = COALESCE(excluded.energy_kcal, nutrition_days.energy_kcal),
+        carbohydrates_g = COALESCE(excluded.carbohydrates_g, nutrition_days.carbohydrates_g),
+        protein_g = COALESCE(excluded.protein_g, nutrition_days.protein_g),
+        fat_g = COALESCE(excluded.fat_g, nutrition_days.fat_g),
+        hydration_ml = COALESCE(excluded.hydration_ml, nutrition_days.hydration_ml),
+        metrics_json = excluded.metrics_json, raw_object_hash = excluded.raw_object_hash`, { provider, nutritionDate, ...fields, metrics: json(payload), rawHash });
     for (const [index, item] of nutritionItems(payload).entries()) {
         const itemFields = nutritionFields(item);
         const itemId = firstString(item, ['id', 'foodId', 'entryId']) ?? `${remoteId}:${index}`;
         await database.run(`INSERT INTO nutrition_items
        (provider, remote_item_id, nutrition_date, meal, consumed_at, food_name, quantity, energy_kcal, carbohydrates_g, protein_g, fat_g, payload_json, raw_object_hash)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       VALUES (
+         CAST(? AS VARCHAR), CAST(? AS VARCHAR), CAST(? AS DATE), CAST(? AS VARCHAR),
+         CAST(? AS TIMESTAMP), CAST(? AS VARCHAR), CAST(? AS DOUBLE), CAST(? AS DOUBLE),
+         CAST(? AS DOUBLE), CAST(? AS DOUBLE), CAST(? AS DOUBLE), CAST(? AS JSON), CAST(? AS VARCHAR)
+       )
        ON CONFLICT (provider, remote_item_id) DO UPDATE SET nutrition_date = excluded.nutrition_date, meal = excluded.meal,
        consumed_at = excluded.consumed_at, food_name = excluded.food_name, quantity = excluded.quantity, energy_kcal = excluded.energy_kcal,
        carbohydrates_g = excluded.carbohydrates_g, protein_g = excluded.protein_g, fat_g = excluded.fat_g, payload_json = excluded.payload_json,

package/dist/elt/storage/database.d.ts

@@ -2,6 +2,7 @@ import { ReadOnlyRepository } from '../../core/query/repository.js';
 import type { CatencePaths } from '../../contracts/runtime.js';
 import type { QueryBindings, WriteDataStore } from '../../contracts/storage.js';
 import type { Provider } from '../../contracts/staging.js';
+import { type InterruptedRuns, type SyncProgressSnapshot, type SyncProgressState } from '../../contracts/progress.js';
 export declare class CatenceDatabase implements WriteDataStore {
     private readonly instance;
     private readonly connection;
@@ -16,7 +17,19 @@ export declare class CatenceDatabase implements WriteDataStore {
     interrupt(): void;
     beginRun(provider: Provider, fromDate: string, runId?: `${string}-${string}-${string}-${string}-${string}`): Promise<string>;
     finishRun(runId: string): Promise<void>;
+    heartbeatRun(runId: string, progress: SyncProgressState): Promise<void>;
+    markRunInterrupted(runId: string, stage?: string): Promise<void>;
+    interruptStaleSyncRuns(timeoutMs?: number): Promise<InterruptedRuns>;
+    syncProgress(timeoutMs?: number): Promise<SyncProgressSnapshot>;
+    hasCalendarEventOlderThan(provider: Provider, beforeIsoDate: string, entityType?: string): Promise<boolean>;
+    deleteMissingCalendarEntities(provider: Provider, entityTypes: readonly string[], keepRemoteIds: readonly string[], minOccurredOn: string): Promise<void>;
     addError(runId: string, provider: Provider, endpoint: string, remoteId: string | null, message: string, retryable: boolean): Promise<void>;
+    resolveErrors(opts?: {
+        runIds?: string[];
+        provider?: Provider;
+        before?: string;
+        all?: boolean;
+    }): Promise<number>;
     status(): Promise<Record<string, unknown>>;
     getRun(runId: string): Promise<{
         provider: Provider;
@@ -45,6 +58,12 @@ export declare class CatenceDatabase implements WriteDataStore {
     activityNeedsDetailSync(provider: Provider, remoteActivityId: string, summaryHash: string): Promise<boolean>;
     recordActivitySyncState(provider: Provider, remoteActivityId: string, summaryHash: string, runId: string, detailsFetched: boolean): Promise<void>;
     knownActivitySummaryHashes(provider: Provider): Promise<Record<string, string>>;
+    hasGarminLactateThresholdHistory(): Promise<boolean>;
+    earliestActivityStartDate(provider: Provider): Promise<string | null>;
+    garminSwimActivitySources(): Promise<Array<{
+        remote_activity_id: string;
+        started_on: string | null;
+    }>>;
     private latestSourceDate;
     private upsertCursor;
 }
@@ -66,9 +85,9 @@ export declare class ReadOnlyCatenceDatabase {
     interrupt(): void;
     private withConnection;
 }
-/** Compose core read services with the DuckDB-backed, read-only adapter. */
-export declare function openReadOnlyRepository(paths: CatencePaths): Promise<ReadOnlyRepository>;
 export declare class ReadOnlyDatabaseError extends Error {
     readonly code: 'data_sync_in_progress' | 'data_unavailable';
     constructor(code: 'data_sync_in_progress' | 'data_unavailable', message: string);
 }
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export declare function openReadOnlyRepository(paths: CatencePaths): Promise<ReadOnlyRepository>;

package/dist/elt/storage/database.js

@@ -2,8 +2,31 @@ import { DuckDBInstance } from '@duckdb/node-api';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { ReadOnlyRepository } from '../../core/query/repository.js';
+import { SYNC_STAGES, STALE_RUN_TIMEOUT_MS } from '../../contracts/progress.js';
 import { migrations } from './migrations.js';
 import { json } from './sql.js';
+/**
+ * DuckDB's node API throws "Cannot create values of type ANY" when a bound
+ * parameter resolves to an untyped value. JS `Date` objects surface as `ANY`
+ * (and are not auto-coerced the way strings are), so any date/timestamp
+ * parameter read back from the database and re-bound crashes the statement.
+ * Serializing dates to ISO strings keeps every parameter concretely typed.
+ */
+function serializeValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    return value;
+}
+function serializeBindings(bindings) {
+    if (!bindings)
+        return bindings;
+    if (Array.isArray(bindings))
+        return bindings.map(serializeValue);
+    const out = {};
+    for (const [key, value] of Object.entries(bindings))
+        out[key] = serializeValue(value);
+    return out;
+}
 export class CatenceDatabase {
     instance;
     connection;
@@ -61,10 +84,10 @@ export class CatenceDatabase {
         }
     }
     async run(sql, values) {
-        await this.connection.run(sql, values);
+        await this.connection.run(sql, serializeBindings(values));
     }
     async rows(sql, values) {
-        const result = await this.connection.runAndReadAll(sql, values);
+        const result = await this.connection.runAndReadAll(sql, serializeBindings(values));
         return result.getRowObjectsJS();
     }
     async tableNames(query) {
@@ -81,11 +104,132 @@ export class CatenceDatabase {
         await this.run(`UPDATE sync_runs SET status = CASE WHEN error_count > 0 THEN 'completed_with_errors' ELSE 'completed' END, completed_at = now() WHERE run_id = $runId`, { runId });
         await this.run("UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context'");
     }
+    async heartbeatRun(runId, progress) {
+        await this.run(`INSERT INTO sync_run_progress (run_id, provider, stage, current_step, completed_units, total_units, percent, elapsed_seconds, estimated_remaining_seconds, heartbeat_at, detail_json)
+       VALUES ($runId, $provider, $stage, $currentStep, $completedUnits, $totalUnits, $percent, $elapsedSeconds, $estimatedRemainingSeconds, now(), '{}')
+       ON CONFLICT (run_id) DO UPDATE SET
+         provider = EXCLUDED.provider,
+         stage = EXCLUDED.stage,
+         current_step = EXCLUDED.current_step,
+         completed_units = EXCLUDED.completed_units,
+         total_units = EXCLUDED.total_units,
+         percent = EXCLUDED.percent,
+         elapsed_seconds = EXCLUDED.elapsed_seconds,
+         estimated_remaining_seconds = EXCLUDED.estimated_remaining_seconds,
+         heartbeat_at = now(),
+         detail_json = '{}'`, {
+            runId,
+            provider: progress.provider,
+            stage: progress.stage,
+            currentStep: progress.currentStep,
+            completedUnits: progress.completedUnits,
+            totalUnits: progress.totalUnits,
+            percent: progress.percentComplete,
+            elapsedSeconds: progress.elapsedSeconds,
+            estimatedRemainingSeconds: progress.estimatedRemainingSeconds,
+        });
+    }
+    async markRunInterrupted(runId, stage = 'interrupted') {
+        await this.run("UPDATE sync_runs SET status = 'interrupted', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId });
+        await this.run('UPDATE sync_run_progress SET stage = $stage, heartbeat_at = now() WHERE run_id = $runId', { runId, stage });
+    }
+    async interruptStaleSyncRuns(timeoutMs = STALE_RUN_TIMEOUT_MS) {
+        const cutoff = new Date(Date.now() - timeoutMs).toISOString();
+        const stale = await this.rows(`SELECT run_id FROM sync_runs WHERE status = 'running' AND started_at < $cutoff`, { cutoff });
+        for (const row of stale) {
+            await this.run("UPDATE sync_runs SET status = 'timed_out', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId: row.run_id });
+            await this.run("UPDATE sync_run_progress SET stage = 'timed_out', heartbeat_at = now() WHERE run_id = $runId", { runId: row.run_id });
+        }
+        return { runIds: stale.map((row) => row.run_id) };
+    }
+    async syncProgress(timeoutMs = STALE_RUN_TIMEOUT_MS) {
+        // A run killed with its container (docker restart, OOM) keeps
+        // status='running' until something cleans it up, and that cleanup only
+        // runs inside a starting sync child — which the busy guard refuses to
+        // spawn while the row reads as active. Age-filtering here mirrors the
+        // sidecar contract: a heartbeat older than the stale timeout can never
+        // block a new run or disable the dashboard's Sync button forever.
+        const cutoff = new Date(Date.now() - timeoutMs).toISOString();
+        const running = await this.rows(`SELECT runs.run_id, runs.provider,
+         coalesce(progress.stage, 'starting') AS stage,
+         progress.current_step AS current_step,
+         coalesce(progress.completed_units, 0) AS completed_units,
+         progress.total_units AS total_units,
+         coalesce(progress.percent, 0) AS percent,
+         coalesce(progress.elapsed_seconds, 0) AS elapsed_seconds,
+         progress.estimated_remaining_seconds AS estimated_remaining_seconds,
+         cast(coalesce(progress.heartbeat_at, runs.started_at) AS VARCHAR) AS heartbeat_at
+       FROM sync_runs AS runs
+       LEFT JOIN sync_run_progress AS progress USING (run_id)
+       WHERE runs.status = 'running'
+         AND coalesce(progress.heartbeat_at, runs.started_at) > $cutoff
+       ORDER BY runs.started_at DESC`, { cutoff });
+        const recent = await this.rows(`SELECT progress.run_id, progress.provider, progress.stage, progress.current_step,
+         progress.completed_units, progress.total_units, progress.percent, progress.elapsed_seconds,
+         progress.estimated_remaining_seconds, cast(progress.heartbeat_at AS VARCHAR) AS heartbeat_at
+       FROM sync_run_progress AS progress
+       ORDER BY progress.heartbeat_at DESC
+       LIMIT 10`);
+        return { running: running.map(toSyncProgressState), recent: recent.map(toSyncProgressState) };
+    }
+    async hasCalendarEventOlderThan(provider, beforeIsoDate, entityType = 'event') {
+        // Coverage signal for the automatic calendar-events backfill: true once
+        // the store already holds an event older than the regular short window,
+        // meaning the one-time deep pull has landed and normal syncs can stay
+        // narrow. Athletes with genuinely no old events re-run the deep window;
+        // it costs one small paginated listing per sync.
+        const rows = await this.rows(`SELECT 1 FROM source_entities WHERE provider = $provider AND entity_type = $entityType AND occurred_on < $before LIMIT 1`, { provider, entityType, before: beforeIsoDate });
+        return rows.length > 0;
+    }
+    async deleteMissingCalendarEntities(provider, entityTypes, keepRemoteIds, minOccurredOn) {
+        // Calendar entities (joined races, scheduled workouts) are mutable and
+        // deletable upstream. Re-fetches upsert survivors via remote_id; this
+        // removes in-window rows absent from the latest authoritative listing so
+        // upstream deletions propagate instead of leaving ghosts forever. Rows
+        // without a date are preserved (they predate strict dating).
+        if (!entityTypes.length)
+            return;
+        const values = { provider, minOccurredOn };
+        const typePlaceholders = entityTypes.map((name, index) => {
+            values[`type${index}`] = name;
+            return `$type${index}`;
+        });
+        let keepClause = '';
+        if (keepRemoteIds.length) {
+            keepClause = ` AND remote_id NOT IN (${keepRemoteIds.map((_, index) => `$keep${index}`).join(', ')})`;
+            keepRemoteIds.forEach((id, index) => { values[`keep${index}`] = id; });
+        }
+        for (const table of ['source_entities', 'domain_entities']) {
+            await this.run(`DELETE FROM ${table} WHERE provider = $provider AND entity_type IN (${typePlaceholders}) AND occurred_on >= $minOccurredOn${keepClause}`, values);
+        }
+    }
     async addError(runId, provider, endpoint, remoteId, message, retryable) {
         await this.run(`INSERT INTO normalization_errors (error_id, run_id, provider, endpoint, remote_id, message, retryable)
        VALUES ($errorId, $runId, $provider, $endpoint, $remoteId, $message, $retryable)`, { errorId: randomUUID(), runId, provider, endpoint, remoteId, message, retryable });
         await this.run('UPDATE sync_runs SET error_count = error_count + 1 WHERE run_id = $runId', { runId });
     }
+    async resolveErrors(opts = {}) {
+        const clauses = ['resolved_at IS NULL'];
+        const values = {};
+        if (opts.runIds && opts.runIds.length > 0) {
+            const placeholders = opts.runIds.map((_, index) => `$runId${index}`).join(', ');
+            clauses.push(`run_id IN (${placeholders})`);
+            opts.runIds.forEach((runId, index) => { values[`runId${index}`] = runId; });
+        }
+        if (opts.provider) {
+            clauses.push('provider = $provider');
+            values.provider = opts.provider;
+        }
+        if (opts.before) {
+            clauses.push('created_at < $before');
+            values.before = opts.before;
+        }
+        if (!opts.all && clauses.length === 1) {
+            throw new Error('Refusing to resolve all unresolved errors without an explicit --all flag.');
+        }
+        const resolved = await this.rows(`UPDATE normalization_errors SET resolved_at = now() WHERE ${clauses.join(' AND ')} RETURNING error_id`, values);
+        return resolved.length;
+    }
     async status() {
         // @duckdb/node-api owns native statement state on the connection. Keep
         // status reads sequential instead of issuing several native calls at once.
@@ -166,6 +310,24 @@ export class CatenceDatabase {
         const rows = await this.rows('SELECT remote_activity_id, summary_hash FROM activity_sync_state WHERE provider = $provider', { provider });
         return Object.fromEntries(rows.map((row) => [row.remote_activity_id, row.summary_hash]));
     }
+    async hasGarminLactateThresholdHistory() {
+        const rows = await this.rows("SELECT count(*) AS n FROM training_metric_observations WHERE observation_id LIKE 'garmin:lactate_threshold:daily:%'");
+        return (rows[0]?.n ?? 0) > 0;
+    }
+    async earliestActivityStartDate(provider) {
+        const rows = await this.rows(`SELECT min(cast(started_at_utc AS DATE)) AS earliest FROM activities activity
+         JOIN activity_sources source USING (activity_id) WHERE source.provider = $provider`, { provider });
+        return toIsoDate(rows[0]?.earliest ?? null);
+    }
+    async garminSwimActivitySources() {
+        const sports = ['lap_swimming', 'swimming', 'open_water_swimming', 'openwaterswimming'];
+        return this.rows(`SELECT source.remote_activity_id, cast(activity.started_at_utc AS VARCHAR) AS started_on
+         FROM activity_sources AS source
+         JOIN activities AS activity USING (activity_id)
+        WHERE source.provider = 'garmin'
+          AND lower(coalesce(activity.sport, '')) IN (${sports.map((sport) => `'${sport}'`).join(', ')})
+        ORDER BY activity.started_at_utc`);
+    }
     async latestSourceDate(provider, cursorName) {
         const observations = cursorName === 'daily'
             ? `SELECT max(metric_date) AS observed_date FROM daily_metrics WHERE provider = $provider
@@ -283,10 +445,6 @@ export class ReadOnlyCatenceDatabase {
         }
     }
 }
-/** Compose core read services with the DuckDB-backed, read-only adapter. */
-export async function openReadOnlyRepository(paths) {
-    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
-}
 export class ReadOnlyDatabaseError extends Error {
     code;
     constructor(code, message) {
@@ -295,4 +453,22 @@ export class ReadOnlyDatabaseError extends Error {
         this.name = 'ReadOnlyDatabaseError';
     }
 }
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export async function openReadOnlyRepository(paths) {
+    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
+}
+function toSyncProgressState(row) {
+    return {
+        runId: row.run_id,
+        provider: row.provider,
+        stage: SYNC_STAGES.includes(row.stage) ? row.stage : 'starting',
+        currentStep: row.current_step,
+        completedUnits: Math.max(0, Number(row.completed_units) || 0),
+        totalUnits: row.total_units === null || row.total_units === undefined ? null : Math.max(0, Number(row.total_units) || 0),
+        percentComplete: Math.min(100, Math.max(0, Number(row.percent) || 0)),
+        elapsedSeconds: Math.max(0, Number(row.elapsed_seconds) || 0),
+        estimatedRemainingSeconds: row.estimated_remaining_seconds === null || row.estimated_remaining_seconds === undefined ? null : Math.max(0, Number(row.estimated_remaining_seconds) || 0),
+        heartbeatAt: row.heartbeat_at,
+    };
+}
 //# sourceMappingURL=database.js.map