catence 0.2.0-beta.8 → 0.2.0

package/dist/elt/ingestion/providers/intervals.js

@@ -2,7 +2,7 @@ import { IntervalsClient } from 'intervals-icu';
 import { randomUUID } from 'node:crypto';
 import { stableJsonHash, storeArtifact, storeJsonArtifact } from '../../storage/artifacts.js';
 import { importRecord, queueWorkItem, completeWorkItem, failWorkItem } from '../importer.js';
-import { intervalsActivityReadEndpoints, intervalsSecondaryReadRegistry, assertReadOnlyRegistry } from './registry.js';
+import { intervalsActivityReadEndpoints, intervalsSecondaryReadRegistry, intervalsEventSyncWindow, assertReadOnlyRegistry } from './registry.js';
 import { intervalsStreamsToSamples, writeParquetSamples } from '../../streams.js';
 const apiBaseUrl = 'https://intervals.icu/api/v1';
 function asObject(value) {
@@ -42,12 +42,14 @@ export class IntervalsExtractor {
     paths;
     apiKey;
     athleteId;
+    log;
     client;
-    constructor(database, paths, apiKey, athleteId) {
+    constructor(database, paths, apiKey, athleteId, log) {
         this.database = database;
         this.paths = paths;
         this.apiKey = apiKey;
         this.athleteId = athleteId;
+        this.log = log;
         // The typed client is used for provider-compatible authentication and the
         // primary identity request. Manifest-only calls below intentionally use
         // the same read-only credentials to cover endpoint families not wrapped by it.
@@ -65,6 +67,21 @@ export class IntervalsExtractor {
         for (const endpoint of intervalsSecondaryReadRegistry) {
             if (endpoint.name === 'athlete')
                 continue;
+            // Calendar events straddle today (past for activity association,
+            // future for planning); they must not inherit the cursor-bounded
+            // activity window, which always ends at today.
+            if (endpoint.name === 'events') {
+                const window = await this.resolveEventsSyncWindow();
+                const payload = await this.capture(runId, 'events', null, window, async () => this.getCollection('events', resolvedAthleteId, window.fromDate, window.toDate));
+                if (payload === undefined)
+                    continue;
+                await this.importEntities('event', 'events', payload, null, runId);
+                // The listing is authoritative: events deleted upstream must not
+                // linger as ghosts in the store once this sync succeeded.
+                const seenIds = asItems(payload).map((item) => idOf(item, '')).filter(Boolean);
+                await this.database.deleteMissingCalendarEntities('intervals', ['event'], seenIds, window.fromDate);
+                continue;
+            }
             if (!activityWindow)
                 continue;
             const { fromDate, toDate } = activityWindow;
@@ -84,6 +101,23 @@ export class IntervalsExtractor {
             }
         }
     }
+    /**
+     * Regular syncs reach back EVENT_WINDOW_PAST_DAYS — just enough to
+     * associate recently finished events with their activities. A store whose
+     * own activity history predates that span gets an automatic one-time
+     * coverage backfill instead: the window stretches to the earliest
+     * activity until an event older than the short window lands (self-
+     * clearing), after which deeper history is the backfill command's job.
+     */
+    async resolveEventsSyncWindow() {
+        const short = intervalsEventSyncWindow();
+        if (await this.database.hasCalendarEventOlderThan('intervals', short.fromDate))
+            return short;
+        const earliest = await this.database.earliestActivityStartDate('intervals');
+        if (!earliest || earliest >= short.fromDate)
+            return short;
+        return { fromDate: earliest, toDate: short.toDate };
+    }
     async captureCollectionChildren(runId, collection, payload, athleteId) {
         const children = {
             events: [{ suffix: (id) => `/athlete/${athleteId}/events/${id}`, entityType: 'event' }],
@@ -189,6 +223,7 @@ export class IntervalsExtractor {
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             await failWorkItem(this.database, workId, message);
+            this.log.warn('Endpoint capture failed', { runId, provider: 'intervals', endpoint, remoteId, error: message });
             await this.database.addError(runId, 'intervals', endpoint, remoteId, message, true);
             return undefined;
         }

package/dist/elt/ingestion/providers/registry.d.ts

@@ -11,6 +11,19 @@ export declare const intervalsReadRegistry: readonly EndpointSpec[];
  * Garmin's activity detail, files, streams, or account data.
  */
 export declare const intervalsSecondaryReadRegistry: EndpointSpec[];
+/** How far back and ahead of today the planned-events fetch reaches. */
+/** Regular syncs look back a month for activity association; deeper history arrives via the automatic coverage backfill. */
+export declare const EVENT_WINDOW_PAST_DAYS = 30;
+export declare const EVENT_WINDOW_FUTURE_DAYS = 365;
+/**
+ * Deliberately cursor-free: activities chase a past-only incremental window,
+ * while calendar events must straddle today so upcoming races and recently
+ * completed ones (associatable with their finished activities) both arrive.
+ */
+export declare function intervalsEventSyncWindow(now?: Date): {
+    fromDate: string;
+    toDate: string;
+};
 export declare const intervalsActivityReadEndpoints: readonly ["activity", "streams", "intervals", "map", "weather", "weather_summary", "best_efforts", "power_curve", "pace_curve", "hr_curve", "power_vs_hr", "hr_load_model", "segments", "messages", "original_file", "fit_file", "gpx_file"];
 /** Read-only methods exposed by python-garminconnect, grouped for manifest tests and worker dispatch. */
 export declare const garminReadRegistry: readonly EndpointSpec[];

package/dist/elt/ingestion/providers/registry.js

@@ -21,7 +21,23 @@ export const intervalsReadRegistry = registry('intervals', [
  * supplies the separately named training calculations without duplicating
  * Garmin's activity detail, files, streams, or account data.
  */
-export const intervalsSecondaryReadRegistry = intervalsReadRegistry.filter((endpoint) => endpoint.name === 'athlete' || endpoint.name === 'activities');
+export const intervalsSecondaryReadRegistry = intervalsReadRegistry.filter((endpoint) => endpoint.name === 'athlete' || endpoint.name === 'activities' || endpoint.name === 'events');
+/** How far back and ahead of today the planned-events fetch reaches. */
+/** Regular syncs look back a month for activity association; deeper history arrives via the automatic coverage backfill. */
+export const EVENT_WINDOW_PAST_DAYS = 30;
+export const EVENT_WINDOW_FUTURE_DAYS = 365;
+/**
+ * Deliberately cursor-free: activities chase a past-only incremental window,
+ * while calendar events must straddle today so upcoming races and recently
+ * completed ones (associatable with their finished activities) both arrive.
+ */
+export function intervalsEventSyncWindow(now = new Date()) {
+    const dayMs = 86_400_000;
+    return {
+        fromDate: new Date(now.getTime() - EVENT_WINDOW_PAST_DAYS * dayMs).toISOString().slice(0, 10),
+        toDate: new Date(now.getTime() + EVENT_WINDOW_FUTURE_DAYS * dayMs).toISOString().slice(0, 10),
+    };
+}
 export const intervalsActivityReadEndpoints = [
     'activity', 'streams', 'intervals', 'map', 'weather', 'weather_summary', 'best_efforts', 'power_curve', 'pace_curve', 'hr_curve',
     'power_vs_hr', 'hr_load_model', 'segments', 'messages', 'original_file', 'fit_file', 'gpx_file',
@@ -43,6 +59,8 @@ export const garminReadRegistry = registry('garmin', [
     ['activity_power_zones', 'activity', 'activity_zone'], ['activity_exercise_sets', 'activity', 'activity_exercise_set'], ['activity_gear', 'activity', 'activity_gear'],
     ['activity_original', 'activity', 'activity_file'], ['activity_tcx', 'activity', 'activity_file'], ['activity_gpx', 'activity', 'activity_file'], ['activity_kml', 'activity', 'activity_file'],
     ['activity_csv', 'activity', 'activity_file'], ['workouts', 'collection', 'workout'], ['scheduled_workouts', 'date_range', 'scheduled_workout'],
+    ['events', 'collection', 'event'],
+    ['course', 'child', 'course'],
     ['training_plans', 'collection', 'training_plan'], ['goals', 'collection', 'goal'], ['personal_records', 'singleton', 'personal_record'],
     ['earned_badges', 'collection', 'badge'], ['available_badges', 'collection', 'badge'], ['challenges', 'collection', 'challenge'],
     ['gear', 'collection', 'gear'], ['golf_summary', 'collection', 'golf_scorecard'], ['golf_user_stats', 'singleton', 'golf_user_stat'],

package/dist/elt/ingestion/providers/strava/service.js

@@ -8,6 +8,7 @@ import { ensurePaths, loadCatenceConfig } from '../../../../core/runtime/configu
 import { athleteProviderEnvironment } from '../../../../core/runtime/secrets.js';
 import { CatenceDatabase, openReadOnlyRepository } from '../../../storage/database.js';
 import { importJsonl } from '../../importer.js';
+import { createSyncLogger } from '../../../../core/logging.js';
 import { withDataWriteLock } from '../../../storage/write-lock.js';
 const execFileAsync = promisify(execFile);
 export class StravaRateLimitError extends Error {
@@ -108,6 +109,7 @@ async function cachedState(database, resourceType, remoteId) {
 async function runReadOperation(paths, operation, extraArgs, resource, refresh = false) {
     return withDataWriteLock(paths, async () => {
         await ensurePaths(paths);
+        const log = createSyncLogger(paths);
         const database = await CatenceDatabase.open(paths);
         try {
             if (!refresh) {
@@ -117,6 +119,7 @@ async function runReadOperation(paths, operation, extraArgs, resource, refresh =
             }
             await checkBudget(database, paths);
             const runId = await database.beginRun('strava', new Date().toISOString().slice(0, 10));
+            log.info('Starting Strava read operation', { runId, operation, resource: resource.id });
             const directory = path.join(paths.staging, 'strava');
             const stagingPath = path.join(directory, `${runId}.jsonl`);
             const resultPath = path.join(directory, `${runId}.result.json`);
@@ -124,17 +127,20 @@ async function runReadOperation(paths, operation, extraArgs, resource, refresh =
             try {
                 result = await invokeWorker(paths, ['--mode', operation, '--run-id', runId, '--output', stagingPath, ...extraArgs], resultPath);
                 if (existsSync(stagingPath))
-                    await importJsonl(database, runId, stagingPath);
+                    await importJsonl(database, runId, stagingPath, log);
                 await storeRateState(database, result);
                 await writeState(database, resource.type, resource.id, result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                log.error('Strava read operation failed', { runId, operation, resource: resource.id, error: message, stack: error instanceof Error ? error.stack : undefined });
                 await database.addError(runId, 'strava', operation, resource.id, message, true);
                 throw error;
             }
             finally {
                 await database.finishRun(runId);
+                const [run] = await database.rows('SELECT status, error_count FROM sync_runs WHERE run_id = $runId', { runId });
+                log.info('Strava read operation finished', { runId, operation, status: run?.status ?? 'unknown', errorCount: run?.error_count ?? 0 });
             }
             if (result.status === 'error')
                 throw new StravaEnrichmentError(result.message ?? 'Strava did not complete the requested enrichment.');

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>;