catence 0.2.0-beta.21 → 0.2.0-beta.23

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

package/dist/interfaces/mcp/main.js

@@ -1,11 +1,42 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync } from 'node:fs';
-import { addAthlete, athleteStorePaths, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, CatenceDatabase, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths } from '../../runtime/index.js';
 import { parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
 import { createCatenceHttpServer } from '../http/server.js';
 import { MCP_USAGE, parseMcpCliOptions } from './cli-options.js';
 import { createCatenceMcpServer } from './server.js';
+async function migrateCatalogStores(home) {
+    // On Docker image bumps the DuckDB schema version increases. The
+    // read-only MCP health probe would otherwise report "version X required"
+    // until the next manual sync. Proactively opening each athlete store in
+    // writable mode runs the idempotent migrations (database.ts:migrate)
+    // before the HTTP server starts listening, so a plain `docker compose up`
+    // after `deploy-console.sh beta` heals existing installs without an extra
+    // manual `catence-data migrate --all` step. Failures are best-effort:
+    // a missing catalog or a store still locked by another process is retried
+    // on the next sync or health check.
+    try {
+        const catalogPaths = resolveCatalogPaths(home);
+        const catalog = await loadCatalog(catalogPaths).catch(() => null);
+        if (!catalog || catalog.athletes.length === 0)
+            return;
+        for (const athlete of catalog.athletes) {
+            const paths = athleteStorePaths(catalogPaths, athlete.id);
+            try {
+                const database = await CatenceDatabase.open(paths);
+                await database.close();
+            }
+            catch {
+                // Best-effort: a lock or a corrupted store must not prevent the
+                // server from starting; the next sync will retry the migration.
+            }
+        }
+    }
+    catch {
+        // Catalog read failures are non-fatal for startup.
+    }
+}
 async function run() {
     const arguments_ = process.argv.slice(2);
     if (arguments_[0] === 'serve') {
@@ -14,6 +45,7 @@ async function run() {
             process.stderr.write(`${SERVE_USAGE}\n`);
             return;
         }
+        await migrateCatalogStores(options.home);
         const httpServer = createCatenceHttpServer({
             catalogPaths: resolveCatalogPaths(options.home),
             allowedOrigins: options.allowedOrigins,