catence 0.2.0-beta.21 → 0.2.0-beta.24

package/dist/core/query/catalog.js

@@ -5,8 +5,8 @@ export const DATASET_CATALOG = {
         columns: [column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('started_at_local', 'VARCHAR'), column('timezone', 'VARCHAR'), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR', { filterable: true }), column('link_state', 'VARCHAR', { filterable: true, groupable: true })],
     },
     canonical_activities: {
-        name: 'canonical_activities', relation: 'canonical_activity_training', description: 'One training interpretation per linked activity; Garmin is canonical when present, while Intervals analysis values remain separately provenance-tagged.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_id', 'activity_source_id', 'provider'], permittedGroupings: ['provider', 'sport'],
-        columns: [column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR'), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('calories', 'DOUBLE', { unit: 'kcal', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('weighted_power', 'DOUBLE', { unit: 'W', metric: true }), column('training_load', 'DOUBLE', { metric: true }), column('rpe', 'DOUBLE', { metric: true }), column('feel', 'DOUBLE', { metric: true })],
+        name: 'canonical_activities', relation: 'canonical_activity_training', description: 'One training interpretation per linked activity; Garmin is canonical when present, while Intervals analysis values remain separately provenance-tagged. A NULL avg_power here does not mean no power was recorded: running/cycling power lives in power_best_facts (Garmin FIT-derived). Use power_coverage_report or read_series on activity_samples rather than inferring absence. derived_avg_power_w is the FIT-derived mean per activity (avg of power_best_facts best_power_w) when summary avg_power is sparse; prefer coalesce(avg_power, derived_avg_power_w) for coverage-aware aggregates. NULL avg_power here does not mean no power; running/cycling power is in power_best_facts (FIT-derived). Use power_coverage_report / read_series.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_id', 'activity_source_id', 'provider'], permittedGroupings: ['provider', 'sport'],
+        columns: [column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR'), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('calories', 'DOUBLE', { unit: 'kcal', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('derived_avg_power_w', 'DOUBLE', { unit: 'W', metric: true, description: 'FIT-derived mean power per activity (avg of power_best_facts best_power_w); complement for sparse avg_power.' }), column('weighted_power', 'DOUBLE', { unit: 'W', metric: true }), column('training_load', 'DOUBLE', { metric: true }), column('rpe', 'DOUBLE', { metric: true }), column('feel', 'DOUBLE', { metric: true })],
     },
     canonical_activity_facts: {
         name: 'canonical_activity_facts', relation: 'canonical_activity_facts', description: 'Field-level canonical activity values. Garmin is preferred when available; the original Garmin and Intervals values, selected source, disagreement, and quality flags remain visible.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_id', 'garmin_activity_source_id', 'intervals_activity_source_id', 'distance_source', 'quality_flags'], permittedGroupings: ['sport', 'link_state', 'distance_source'],
@@ -17,7 +17,7 @@ export const DATASET_CATALOG = {
         columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('remote_activity_id', 'VARCHAR', { filterable: true }), column('external_id', 'VARCHAR', { filterable: true }), column('raw_object_hash', 'VARCHAR')],
     },
     activity_summaries: {
-        name: 'activity_summaries', relation: 'activity_summary_facts', description: 'Provider activity summary metrics with activity and timestamp provenance.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'activity_id', 'provider', 'raw_object_hash'], permittedGroupings: ['provider', 'sport'],
+        name: 'activity_summaries', relation: 'activity_summary_facts', description: 'Provider activity summary metrics with activity and timestamp provenance. A NULL avg_power does not mean no power; FIT-derived power is in power_best_facts. Prefer power_coverage_report or read_series over inferring absence. NULL avg_power here does not mean no power; running/cycling power is in power_best_facts (FIT-derived). Use power_coverage_report / read_series.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'activity_id', 'provider', 'raw_object_hash'], permittedGroupings: ['provider', 'sport'],
         columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR', { filterable: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('calories', 'DOUBLE', { unit: 'kcal', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('weighted_power', 'DOUBLE', { unit: 'W', metric: true }), column('avg_cadence', 'DOUBLE', { unit: 'rpm', metric: true }), column('training_load', 'DOUBLE', { metric: true }), column('rpe', 'DOUBLE', { metric: true }), column('feel', 'DOUBLE', { metric: true })],
     },
     activity_intervals: {
@@ -25,7 +25,7 @@ export const DATASET_CATALOG = {
         columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('interval_key', 'VARCHAR', { filterable: true }), column('label', 'VARCHAR', { filterable: true, groupable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('start_s', 'DOUBLE', { unit: 's', metric: true }), column('end_s', 'DOUBLE', { unit: 's', metric: true }), column('duration_s', 'DOUBLE', { unit: 's', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_pace', 'DOUBLE', { metric: true }), column('intensity', 'DOUBLE', { metric: true })],
     },
     swim_lengths: {
-        name: 'swim_lengths', relation: 'swim_length_facts', description: 'Explicit provider-supplied swim-length facts. An empty result means lengths were not supplied; Catence does not infer them from activity samples.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'source', 'confidence', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'source', 'confidence', 'is_rest'],
+        name: 'swim_lengths', relation: 'swim_length_facts', description: 'Explicit provider-supplied swim-length facts. An empty result means lengths were not supplied; Catence does not infer them from activity samples. Per-length swolf may be null (not supplied by all providers); derive as duration_s + stroke_count. Per-length distance is typically null in Garmin FIT; use pool_length_m to compute pace (duration_s / pool_length_m * 100 for s/100m).', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'source', 'confidence', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'source', 'confidence', 'is_rest'],
         columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('source', 'VARCHAR', { filterable: true, groupable: true }), column('confidence', 'VARCHAR', { filterable: true, groupable: true }), column('length_index', 'INTEGER', { filterable: true, groupable: true }), column('lap_index', 'INTEGER', { filterable: true, groupable: true }), column('pool_length_m', 'DOUBLE', { unit: 'm', metric: true }), column('start_time', 'TIMESTAMPTZ', { filterable: true }), column('duration_s', 'DOUBLE', { unit: 's', metric: true }), column('active_duration_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('stroke_count', 'DOUBLE', { unit: 'count', metric: true }), column('stroke_rate', 'DOUBLE', { unit: 'strokes/min', metric: true }), column('swolf', 'DOUBLE', { metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('is_rest', 'BOOLEAN', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
     },
     swim_sets: {
@@ -60,6 +60,10 @@ export const DATASET_CATALOG = {
         name: 'power_bests', relation: 'power_best_facts', description: 'Power-duration bests derived from Garmin FIT streams; they are labelled derived while retaining the Garmin activity provenance.', dateColumn: 'started_at_utc', provenanceColumns: ['provider', 'activity_source_id', 'source_type', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'duration_s', 'source_type'],
         columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('duration_s', 'INTEGER', { filterable: true, groupable: true }), column('best_power_w', 'DOUBLE', { unit: 'W', metric: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
     },
+    activity_decoupling: {
+        name: 'activity_decoupling', relation: 'activity_decoupling_facts', description: 'Persisted per-activity aerobic decoupling (Pa:Hr, pct) and grade-adjusted pace (s/km) with provenance. source_type provider means the provider payload supplied the value (authoritative); derived values are tagged locally. Values never overwrite provider output. Not a physiological performance model.', dateColumn: 'started_at_utc', provenanceColumns: ['provider', 'activity_source_id', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'metric', 'source_type'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('metric', 'VARCHAR', { filterable: true, groupable: true }), column('value_number', 'DOUBLE', { metric: true }), column('unit', 'VARCHAR', { filterable: true, groupable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
     nutrition_days: {
         name: 'nutrition_days', relation: 'nutrition_days', description: 'Daily nutrition totals, never a replacement for the item-level food log.', dateColumn: 'nutrition_date', provenanceColumns: ['provider', 'raw_object_hash'], permittedGroupings: ['provider'],
         columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('nutrition_date', 'DATE', { filterable: true, groupable: true }), column('energy_kcal', 'DOUBLE', { unit: 'kcal', metric: true }), column('carbohydrates_g', 'DOUBLE', { unit: 'g', metric: true }), column('protein_g', 'DOUBLE', { unit: 'g', metric: true }), column('fat_g', 'DOUBLE', { unit: 'g', metric: true }), column('hydration_ml', 'DOUBLE', { unit: 'ml', metric: true }), column('raw_object_hash', 'VARCHAR')],

package/dist/core/query/events.d.ts

@@ -0,0 +1,34 @@
+import { ReadOnlyRepository } from './repository.js';
+/** A courseId resolved from an event (or activity) payload, or null when absent. */
+export type ResolvedCourseId = string | null;
+export interface ResolveEventCourseResult {
+    eventId: string;
+    provider: string | null;
+    courseId: ResolvedCourseId;
+    courseSynced: boolean;
+    geometrySampleCount: number;
+    caveats: string[];
+}
+export interface DiffCourseProfilesResult {
+    eventCourseId: ResolvedCourseId;
+    pastActivityCourseId: ResolvedCourseId;
+    sameCourse: boolean | null;
+    differentCourse: boolean | null;
+    caveats: string[];
+}
+/** Pull a courseId from a Garmin/Intervals event/activity payload, tolerating the
+ * common key spellings and a nested `course.id` shape. Returns null when the
+ * payload carries no course reference rather than guessing. */
+export declare function extractCourseId(payload: unknown): ResolvedCourseId;
+export declare class EventsService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    /** Resolve an event's referenced Garmin courseId and report whether its
+     * geometry has been synced. When geometry is absent, the result carries an
+     * explicit caveat so the agent never silently reuses a prior course profile. */
+    resolveEventCourse(eventId: string): Promise<ResolveEventCourseResult>;
+    /** Compare an event's course against a past activity's course. A different
+     * courseId means the prior profile does not apply; an absent reference is
+     * reported as unknown rather than assumed equal. */
+    diffCourseProfiles(eventCourseId: ResolvedCourseId, pastActivityId?: string): Promise<DiffCourseProfilesResult>;
+}

package/dist/core/query/events.js

@@ -0,0 +1,121 @@
+const COURSE_ID_KEYS = ['courseId', 'course_id', 'courseID'];
+/** Pull a courseId from a Garmin/Intervals event/activity payload, tolerating the
+ * common key spellings and a nested `course.id` shape. Returns null when the
+ * payload carries no course reference rather than guessing. */
+export function extractCourseId(payload) {
+    let normalized = payload;
+    if (typeof payload === 'string') {
+        try {
+            normalized = JSON.parse(payload);
+        }
+        catch {
+            normalized = {};
+        }
+    }
+    const record = (typeof normalized === 'object' && normalized !== null && !Array.isArray(normalized)
+        ? normalized
+        : {});
+    for (const key of COURSE_ID_KEYS) {
+        const value = record[key];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+        if (typeof value === 'number' && Number.isFinite(value))
+            return String(value);
+    }
+    const nested = record.course;
+    if (nested !== null && typeof nested === 'object' && !Array.isArray(nested)) {
+        const nestedId = nested.id;
+        if (typeof nestedId === 'string' && nestedId.length > 0)
+            return nestedId;
+        if (typeof nestedId === 'number' && Number.isFinite(nestedId))
+            return String(nestedId);
+    }
+    return null;
+}
+export class EventsService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /** Resolve an event's referenced Garmin courseId and report whether its
+     * geometry has been synced. When geometry is absent, the result carries an
+     * explicit caveat so the agent never silently reuses a prior course profile. */
+    async resolveEventCourse(eventId) {
+        const caveats = [];
+        const events = await this.repository.rows(`SELECT provider, payload_json FROM source_entities
+       WHERE entity_type = 'event' AND remote_id = $eventId
+       ORDER BY provider = 'garmin' DESC, remote_id LIMIT 1`, { eventId });
+        if (events.length === 0) {
+            return {
+                eventId,
+                provider: null,
+                courseId: null,
+                courseSynced: false,
+                geometrySampleCount: 0,
+                caveats: [`No event source entity found for eventId ${eventId}.`],
+            };
+        }
+        const event = events[0];
+        const courseId = extractCourseId(event.payload_json);
+        if (courseId === null) {
+            return {
+                eventId,
+                provider: event.provider,
+                courseId: null,
+                courseSynced: false,
+                geometrySampleCount: 0,
+                caveats: [`Event ${eventId} does not reference a courseId; no course profile to resolve.`],
+            };
+        }
+        const synced = await this.repository.rows(`SELECT remote_id FROM source_entities
+       WHERE entity_type = 'course' AND remote_id = $courseId LIMIT 1`, { courseId });
+        const geometry = await this.repository.rows(`SELECT count(*) AS sample_count FROM course_geometry WHERE course_id = $courseId`, { courseId });
+        const geometrySampleCount = geometry.length > 0 ? Number(geometry[0].sample_count) : 0;
+        const courseSynced = synced.length > 0 && geometrySampleCount > 0;
+        if (!courseSynced) {
+            caveats.push(`Course geometry for courseId ${courseId} is not yet synced; this year's gradient is unverified until a recon run maps to that course. Do not reuse a prior course profile.`);
+        }
+        return {
+            eventId,
+            provider: event.provider,
+            courseId,
+            courseSynced,
+            geometrySampleCount,
+            caveats,
+        };
+    }
+    /** Compare an event's course against a past activity's course. A different
+     * courseId means the prior profile does not apply; an absent reference is
+     * reported as unknown rather than assumed equal. */
+    async diffCourseProfiles(eventCourseId, pastActivityId) {
+        const caveats = [];
+        let pastActivityCourseId = null;
+        if (pastActivityId) {
+            const activities = await this.repository.rows(`SELECT payload_json FROM source_entities
+         WHERE entity_type = 'activity' AND remote_id = $activityId LIMIT 1`, { activityId: pastActivityId });
+            if (activities.length > 0) {
+                pastActivityCourseId = extractCourseId(activities[0].payload_json);
+            }
+            else {
+                caveats.push(`No activity source entity found for pastActivityId ${pastActivityId}; could not resolve its course.`);
+            }
+        }
+        let sameCourse = null;
+        let differentCourse = null;
+        if (eventCourseId !== null && pastActivityCourseId !== null) {
+            sameCourse = eventCourseId === pastActivityCourseId;
+            differentCourse = !sameCourse;
+            if (differentCourse) {
+                caveats.push(`Event courseId ${eventCourseId} differs from past activity courseId ${pastActivityCourseId}; do not reuse the prior course profile.`);
+            }
+        }
+        else if (eventCourseId === null) {
+            caveats.push('Event courseId is unknown; a prior course profile cannot be validated against it.');
+        }
+        else {
+            caveats.push('Past activity courseId is unknown; a prior course profile cannot be confirmed or refuted.');
+        }
+        return { eventCourseId, pastActivityCourseId, sameCourse, differentCourse, caveats };
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/core/query/fitness.d.ts

@@ -26,6 +26,9 @@ export type LatestCyclingActivitiesRequest = FitnessDateRange & {
     includeMultisport?: boolean;
     limit?: number;
 };
+export type ReadinessBaselineRequest = FitnessDateRange & {
+    sport?: string;
+};
 /** Read-only, source-aware fitness projections built on normalized facts. */
 export declare class FitnessService {
     private readonly repository;
@@ -36,5 +39,6 @@ export declare class FitnessService {
     powerCoverageReport(request?: PowerCoverageReportRequest): Promise<Record<string, unknown>>;
     latestCyclingActivities(request?: LatestCyclingActivitiesRequest): Promise<Record<string, unknown>>;
     cyclingProgressReport(request?: FitnessDateRange): Promise<Record<string, unknown>>;
+    readinessBaseline(request?: ReadinessBaselineRequest): Promise<Record<string, unknown>>;
 }
 export {};

package/dist/core/query/fitness.js

@@ -293,5 +293,65 @@ export class FitnessService {
             ],
         };
     }
+    async readinessBaseline(request = {}) {
+        const sport = request.sport ?? 'running';
+        const isRunning = /run/i.test(sport);
+        const values = { sport };
+        const metricClauses = [
+            `metric_name IN ('running_lactate_threshold_pace_s_per_km','running_lactate_threshold_power_w','running_lactate_threshold_hr_bpm','running_lactate_threshold_power_w_kg','race_prediction_time5_k','race_prediction_time10_k','race_prediction_time_half_marathon','race_prediction_time_marathon','training_status_fitness_trend','endurance_score_overall_score')`,
+            `(lower(sport) = lower($sport) OR lower(sport) = 'generic')`,
+            ...addDateRange('observed_at', request, values),
+        ];
+        const observations = await this.repository.rows(`
+      SELECT observation_id, cast(observed_at AS VARCHAR) AS observed_at, value_number, value_text, unit, sport,
+        source_type, source_remote_id, activity_source_id, raw_object_hash, metric_name
+      FROM training_metric_observations
+      WHERE ${metricClauses.join(' AND ')}
+      ORDER BY observed_at DESC, observation_id DESC
+    `, values);
+        const [vo2max, powerCurve, powerCoverage] = await Promise.all([
+            this.vo2MaxHistory({ ...request, sport }),
+            this.powerCurveTrend({ ...request, sportFamily: isRunning ? 'running' : 'cycling' }),
+            this.powerCoverageReport({ ...request, sportFamily: isRunning ? 'running' : 'cycling' }),
+        ]);
+        const byMetric = new Map();
+        for (const row of observations) {
+            const arr = byMetric.get(row.metric_name) ?? [];
+            arr.push(row);
+            byMetric.set(row.metric_name, arr);
+        }
+        const latest = (name) => byMetric.get(name)?.[0] ?? null;
+        const series = (name) => byMetric.get(name) ?? [];
+        return {
+            data: {
+                sport,
+                lactateThreshold: {
+                    pace_s_per_km: latest('running_lactate_threshold_pace_s_per_km'),
+                    power_w: latest('running_lactate_threshold_power_w'),
+                    hr_bpm: latest('running_lactate_threshold_hr_bpm'),
+                    power_w_kg: latest('running_lactate_threshold_power_w_kg'),
+                    powerSeries: series('running_lactate_threshold_power_w'),
+                },
+                vo2max,
+                racePrediction: {
+                    time5_k: latest('race_prediction_time5_k'),
+                    time10_k: latest('race_prediction_time10_k'),
+                    timeHalfMarathon: latest('race_prediction_time_half_marathon'),
+                    timeMarathon: latest('race_prediction_time_marathon'),
+                },
+                fitnessTrend: latest('training_status_fitness_trend'),
+                enduranceScore: latest('endurance_score_overall_score'),
+                powerCurve,
+                powerCoverage,
+            },
+            provenance: { dataset: 'training_metric_observations', powerDataset: 'power_best_facts' },
+            query: request,
+            caveats: [
+                'Readiness baseline is descriptive, not a physiological performance model; it combines lactate threshold, VO₂max, race prediction, fitness trend, and FIT-derived power.',
+                'Running power uses Garmin FIT-derived power bests (power_best_facts), not sparse activity-summary average power; a NULL summary avg_power does not mean no power.',
+                'Course/elevation profile for a specific race is not included here; call resolve_event_course(eventId) before reusing any prior course profile.',
+            ],
+        };
+    }
 }
 //# sourceMappingURL=fitness.js.map

package/dist/core/query/swimming.js

@@ -86,7 +86,7 @@ export class SwimmingService {
                 availability: {
                     explicitLengthFacts: lengths.length > 0,
                     setFacts: sets.length > 0,
-                    perLengthPaceAvailable: lengths.some((length) => Number(length.duration_s) > 0 && Number(length.distance_m) > 0),
+                    perLengthPaceAvailable: lengths.some((length) => Number(length.duration_s) > 0),
                 },
             };
         }));
@@ -123,7 +123,7 @@ export class SwimmingService {
         FROM activity_quality_flags GROUP BY activity_source_id
       ), lengths AS (
         SELECT activity_source_id, count(*) AS length_fact_count,
-          count(*) FILTER (WHERE duration_s > 0 AND distance_m > 0) AS pace_length_fact_count
+          count(*) FILTER (WHERE duration_s > 0) AS pace_length_fact_count
         FROM swim_lengths GROUP BY activity_source_id
       ), sets AS (
         SELECT activity_source_id, count(*) AS set_fact_count FROM swim_sets GROUP BY activity_source_id

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

@@ -60,6 +60,7 @@ export const garminReadRegistry = registry('garmin', [
     ['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/normalization/normalizers.js

@@ -253,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') {
@@ -290,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);
@@ -519,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');

package/dist/elt/storage/migrations.js

@@ -852,5 +852,125 @@ const syncRunProgressMigration = {
     UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
   `,
 };
-export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration];
+const canonicalTrainingDerivedAvgPowerMigration = {
+    version: 15,
+    name: 'canonical_training_derived_avg_power_w',
+    sql: `
+    -- A2: Stop "NULL avg_power => no power" inference without rewriting provenance.
+    -- activity_summaries.avg_power is sparse (NULL for many 2024 running
+    -- activities) while authoritative Garmin FIT-derived power is present as
+    -- per-duration rows in activity_power_bests (exposed as power_best_facts).
+    -- Overwriting the summary value would conflate two layers and break the
+    -- provenance contract (summary vs FIT-derived). Instead, extend the
+    -- canonical view with a derived column that aggregates the FIT signal:
+    -- derived_avg_power_w is the per-activity mean of best_power_w across
+    -- all stored durations. Callers should prefer
+    -- coalesce(avg_power, derived_avg_power_w) or use power_coverage_report /
+    -- read_series on activity_samples for the full signal. NULL remains NULL
+    -- when no FIT bests exist for that activity, making absence explicit.
+    -- Idempotent via CREATE OR REPLACE VIEW; no table mutation.
+    -- Older test fixtures (v9) created activity_summaries with only a subset
+    -- of columns; ensure the full canonical set exists so this view's
+    -- intervals_analysis (which unconditionally references training_load etc.)
+    -- does not throw Binder Error on upgrade.
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS elevation_gain_m DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS calories DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS max_hr DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS avg_power DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS weighted_power DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS avg_cadence DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS training_load DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS rpe DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS feel DOUBLE;
+    CREATE OR REPLACE VIEW canonical_activity_training AS
+    WITH ranked AS (
+      SELECT a.*, source.activity_source_id, source.provider, source.remote_activity_id, source.raw_object_hash,
+        summary.*, row_number() OVER (
+          PARTITION BY a.activity_id
+          ORDER BY CASE source.provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END
+        ) AS source_rank
+      FROM activities a
+      JOIN activity_sources source USING (activity_id)
+      LEFT JOIN activity_summaries summary USING (activity_source_id)
+    ), intervals_analysis AS (
+      SELECT source.activity_id,
+        max(summary.training_load) AS intervals_training_load,
+        max(summary.rpe) AS intervals_rpe,
+        max(summary.feel) AS intervals_feel,
+        max(summary.weighted_power) AS intervals_weighted_power
+      FROM activity_sources source
+      JOIN activity_summaries summary USING (activity_source_id)
+      WHERE source.provider = 'intervals'
+      GROUP BY source.activity_id
+    ), derived_power AS (
+      SELECT activity_source_id, avg(best_power_w) AS derived_avg_power_w
+      FROM activity_power_bests
+      GROUP BY activity_source_id
+    )
+    SELECT ranked.* EXCLUDE (source_rank),
+      intervals_analysis.intervals_training_load,
+      intervals_analysis.intervals_rpe,
+      intervals_analysis.intervals_feel,
+      intervals_analysis.intervals_weighted_power,
+      derived_power.derived_avg_power_w
+    FROM ranked
+    LEFT JOIN intervals_analysis USING (activity_id)
+    LEFT JOIN derived_power USING (activity_source_id)
+    WHERE source_rank = 1;
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+const courseGeometryMigration = {
+    version: 16,
+    name: 'course_geometry',
+    sql: `
+    -- A4: Garmin course/route geometry so a race's elevation/grade profile can be
+    -- resolved and compared against a prior activity's course. garminconnect
+    -- 0.3.x has no dedicated course method, so courses are staged from the raw
+    -- Connect API (connectapi("course-service/course/{id}"), validated live:
+    -- returns metadata + a geoPoints geometry array) and normalized here.
+    -- courseId is the Garmin course identifier referenced by an event's courseId.
+    CREATE TABLE IF NOT EXISTS course_geometry (
+      course_id VARCHAR NOT NULL,
+      seq INTEGER NOT NULL,
+      lat DOUBLE,
+      lon DOUBLE,
+      altitude_m DOUBLE,
+      distance_m DOUBLE,
+      raw_object_hash VARCHAR,
+      PRIMARY KEY (course_id, seq)
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+const activityDecouplingFactsMigration = {
+    version: 17,
+    name: 'activity_decoupling_facts',
+    sql: `
+    -- A3 (persistence): make aerobic decoupling (Pa:Hr) and grade-adjusted pace
+    -- (GAP) queryable historically instead of only inside one activity's raw
+    -- metrics_json. Rows are provider-supplied when the provider payload carries
+    -- them (source_type 'provider'); locally derived values are tagged 'derived'
+    -- with caveats_json. Provider values remain authoritative and are never
+    -- overwritten by derivation.
+    CREATE TABLE IF NOT EXISTS activity_decoupling_facts (
+      provider VARCHAR NOT NULL,
+      activity_source_id VARCHAR NOT NULL,
+      sport VARCHAR,
+      started_at_utc TIMESTAMPTZ,
+      metric VARCHAR NOT NULL,
+      value_number DOUBLE,
+      unit VARCHAR,
+      source_type VARCHAR NOT NULL,
+      caveats_json JSON,
+      raw_object_hash VARCHAR,
+      PRIMARY KEY (provider, activity_source_id, metric)
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration, canonicalTrainingDerivedAvgPowerMigration, courseGeometryMigration, activityDecouplingFactsMigration];
 //# sourceMappingURL=migrations.js.map

package/dist/interfaces/cli/commands.js

@@ -2,7 +2,7 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
     .description('Athlete-scoped Catence data setup, extraction, and normalization.')
@@ -277,5 +277,41 @@ program
     const runIds = Array.isArray(options.run) ? options.run : options.run ? [options.run] : undefined;
     process.stdout.write(`${JSON.stringify(await resolveExtractionErrors(paths, { runIds, provider: options.provider, before: options.before, all: options.all }), null, 2)}\n`);
 });
+program
+    .command('migrate')
+    .description('Apply pending DuckDB schema migrations. Without --all it migrates the selected --athlete store; with --all it migrates every athlete in the catalog.')
+    .option('--all', 'migrate every athlete in the catalog')
+    .option('--home <directory>', 'Catence catalog home directory (also accepts global --home)')
+    .action(async (options) => {
+    const effectiveHome = options.home ?? program.opts().home;
+    const effectiveCatalog = effectiveHome ? resolveCatalogPaths(effectiveHome) : currentCatalog();
+    const migratePaths = async (paths) => {
+        const database = await CatenceDatabase.open(paths);
+        const applied = await database.rows('SELECT version FROM schema_migrations ORDER BY version');
+        await database.close();
+        return { migrated: true, appliedVersions: applied.map((row) => row.version) };
+    };
+    if (options.all) {
+        const catalog = await loadCatalog(effectiveCatalog);
+        const results = {};
+        for (const athlete of catalog.athletes) {
+            const paths = athleteStorePaths(effectiveCatalog, athlete.id);
+            try {
+                results[athlete.id] = await migratePaths(paths);
+            }
+            catch (error) {
+                results[athlete.id] = { migrated: false, error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+        process.stdout.write(`${JSON.stringify({ catalog: effectiveCatalog.root, results }, null, 2)}\n`);
+        return;
+    }
+    const athleteId = program.opts().athlete;
+    if (!athleteId)
+        throw new Error('--athlete is required for this command. Run catence-data athlete list to inspect the catalog or use --all.');
+    const { athlete, paths } = await resolveAthlete(effectiveCatalog, athleteId);
+    const result = await migratePaths(paths);
+    process.stdout.write(`${JSON.stringify({ athleteId: athlete.id, ...result }, null, 2)}\n`);
+});
 await program.parseAsync();
 //# sourceMappingURL=commands.js.map