catence 0.2.0 → 0.2.1-beta.10

package/dist/elt/application/management.js

@@ -19,7 +19,7 @@ import { completeStravaAuthorization, disconnectStrava, getStravaAuthorizationUr
 import { setManualActivityLink, unlinkActivitySource } from '../normalization/activities/linking.js';
 import { importSourceEntity } from '../normalization/normalizers.js';
 import { CatenceDatabase, openReadOnlyRepository, ReadOnlyDatabaseError } from '../storage/database.js';
-import { mergeProgress, ProgressPump, readRunningProgress, removeProgressSidecar } from '../storage/progress-sidecar.js';
+import { mergeProgress, ProgressPump, readRunningProgress, removeProgressSidecar, writeProgressSidecar, PROGRESS_KEEPALIVE_MS } from '../storage/progress-sidecar.js';
 import { withDataWriteLock } from '../storage/write-lock.js';
 function packageRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
@@ -207,7 +207,21 @@ function runGarminWorker(runId, arguments_, environment, pump, log, onInterruptR
             }
             log.info(`[garmin] ${line}`);
         });
-        buffer(child.stderr, (line) => log.error(`[garmin] ${line}`));
+        buffer(child.stderr, (line) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                log.error(`[garmin] ${line}`);
+                return;
+            }
+            if (typeof parsed === 'object' && parsed !== null && parsed.kind === 'stage_timings') {
+                log.info('Garmin staging worker stage timings', parsed);
+                return;
+            }
+            log.error(`[garmin] ${line}`);
+        });
         child.on('error', (error) => {
             if (killTimer)
                 clearTimeout(killTimer);
@@ -310,7 +324,9 @@ async function syncProvider(database, paths, provider, options, log) {
             // streams even when the list-summary hash is unchanged.
             await writeFile(knownActivities, JSON.stringify(options.refreshActivities ? {} : await database.knownActivitySummaryHashes('garmin')));
             extractionStarted = true;
-            const arguments_ = ['run', 'python', '-m', 'python.catence.providers.garmin.cli', '--from', fromDate, '--to', options.toDate, '--data-dir', paths.root, '--output', output, '--run-id', runId, '--known-activities', knownActivities];
+            const requestedConcurrency = Number.parseInt(process.env.CATENCE_GARMIN_CONCURRENCY ?? '5', 10);
+            const workerConcurrency = Number.isFinite(requestedConcurrency) && requestedConcurrency > 0 ? Math.trunc(requestedConcurrency) : 5;
+            const arguments_ = ['run', 'python', '-m', 'python.catence.providers.garmin.cli', '--from', fromDate, '--to', options.toDate, '--data-dir', paths.root, '--output', output, '--run-id', runId, '--known-activities', knownActivities, '--concurrency', String(workerConcurrency)];
             if (dailyWindow)
                 arguments_.push('--daily-from', dailyWindow.fromDate, '--daily-to', dailyWindow.toDate);
             else
@@ -340,6 +356,7 @@ async function syncProvider(database, paths, provider, options, log) {
             if (needsEventBackfill && earliestActivity && earliestActivity < eventsShortFrom) {
                 arguments_.push('--events-from', earliestActivity);
             }
+            const workerStartedAt = Date.now();
             let interruptChild = null;
             await runWithInterruptGuard(runId, database, () => interruptChild?.(), guard, async () => {
                 const outcome = await runGarminWorker(runId, arguments_, {
@@ -350,14 +367,21 @@ async function syncProvider(database, paths, provider, options, log) {
                     throw new Error(`Garmin staging worker exited with code ${outcome.code}${outcome.signal ? ` (${outcome.signal})` : ''}.`);
                 }
             });
+            log.info('Garmin staging worker finished', { runId, durationMs: Date.now() - workerStartedAt, concurrency: workerConcurrency });
             if (!guard.interrupted) {
                 if (!existsSync(output))
                     throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
+                let phaseStartedAt = Date.now();
                 await importJsonl(database, runId, output, log);
+                log.info('Garmin staging import finished', { runId, durationMs: Date.now() - phaseStartedAt });
+                phaseStartedAt = Date.now();
                 await reconcileGarminCalendarEntities(database, output);
+                log.info('Garmin calendar reconciliation finished', { runId, durationMs: Date.now() - phaseStartedAt });
                 if (provider === 'garmin') {
                     try {
+                        phaseStartedAt = Date.now();
                         await backfillGarminSwimLengths(database, paths, runId, log);
+                        log.info('Garmin swim-length backfill finished', { runId, durationMs: Date.now() - phaseStartedAt });
                     }
                     catch (error) {
                         log.warn('Garmin swim-length backfill after sync failed', {
@@ -430,8 +454,43 @@ export async function syncData(paths, provider, explicitFrom, advanceCursor = tr
             runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }, log));
         const executedRuns = runs.filter((run) => !run.skipped);
         if (executedRuns.length > 0) {
-            const index = await buildRetrievalIndex(database);
-            log.info('Rebuilt retrieval index after sync', { documents: index.documents, mode: index.mode, watermark: index.watermark });
+            // The per-provider pumps already stopped (sidecars removed, runs marked
+            // completed), but buildRetrievalIndex still holds the single-writer DB
+            // lock, so /dashboard reads as unavailable. Hold a non-terminal sidecar
+            // for the last executed run so /sync/status keeps reporting running and
+            // the Status Sync button stays disabled through local post-processing.
+            const last = [...executedRuns].reverse().find((run) => run.runId);
+            let indexingKeepalive = null;
+            const holdIndexingProgress = () => last?.runId
+                ? writeProgressSidecar(paths, last.runId, {
+                    ...baseProgress(last.runId, last.provider, 'importing'),
+                    currentStep: 'building retrieval index',
+                    percentComplete: 99,
+                }).catch((error) => {
+                    log.debug('Indexing progress sidecar write failed', {
+                        runId: last.runId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                })
+                : Promise.resolve();
+            if (last?.runId) {
+                await holdIndexingProgress();
+                indexingKeepalive = setInterval(() => {
+                    void holdIndexingProgress();
+                }, PROGRESS_KEEPALIVE_MS);
+                indexingKeepalive.unref?.();
+            }
+            try {
+                const indexStartedAt = Date.now();
+                const index = await buildRetrievalIndex(database);
+                log.info('Rebuilt retrieval index after sync', { documents: index.documents, mode: index.mode, watermark: index.watermark, durationMs: Date.now() - indexStartedAt });
+            }
+            finally {
+                if (indexingKeepalive)
+                    clearInterval(indexingKeepalive);
+                if (last?.runId)
+                    await removeProgressSidecar(paths, last.runId).catch(() => undefined);
+            }
         }
         return { runIds: runs.flatMap((run) => run.runId ? [run.runId] : []), runs, timedOutRuns: timedOutRuns.runIds };
     }
@@ -688,6 +747,36 @@ export async function reimportNutrition(paths) {
         await database.close();
     }
 }
+/**
+ * Re-run normalization over already-captured Garmin weigh-in entities without
+ * contacting any provider. Stores synced before beta.5 staged weigh_ins
+ * payloads but never projected them to daily_metrics, so this backfills
+ * weight_kg from stored payloads. Idempotent upserts make it safe to re-run.
+ */
+export async function reimportWeight(paths) {
+    if (!existsSync(paths.database))
+        throw new Error('No Catence database exists yet. Complete a sync before re-importing weight.');
+    const database = await CatenceDatabase.open(paths);
+    try {
+        const rows = await database.rows(`SELECT provider, entity_type, remote_id, parent_remote_id, occurred_on, source_updated_at, raw_object_hash,
+              cast(payload_json AS VARCHAR) AS payload_json, cast(extension_json AS VARCHAR) AS extension_json
+       FROM source_entities
+       WHERE provider = 'garmin' AND entity_type = 'body_composition'
+       ORDER BY occurred_on, remote_id`);
+        for (const row of rows) {
+            await importSourceEntity(database, {
+                kind: 'source_entity', schemaVersion: 1, provider: row.provider, entityType: row.entity_type,
+                remoteId: row.remote_id, parentRemoteId: row.parent_remote_id, occurredOn: row.occurred_on, sourceUpdatedAt: row.source_updated_at,
+                rawObjectHash: row.raw_object_hash, payload: parseJsonObject(row.payload_json), extension: parseJsonObject(row.extension_json),
+            });
+        }
+        const weights = (await database.rows(`SELECT count(*) AS count FROM daily_metrics WHERE metric_name = 'weight_kg'`))[0]?.count ?? 0;
+        return { reimportedEntities: rows.length, weightObservations: Number(weights) };
+    }
+    finally {
+        await database.close();
+    }
+}
 function parseJsonObject(value) {
     if (!value)
         return {};

package/dist/elt/normalization/normalizers.js

@@ -254,6 +254,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);
+        await importActivityRunDynamics(database, entity.provider, entity.remoteId, payload, rawHash);
         if (entity.provider === 'intervals')
             await importIntervalsAutoSwimSets(database, entity.remoteId, payload, rawHash);
         if (entity.provider === 'garmin') {
@@ -271,6 +272,8 @@ export async function importSourceEntity(database, entity) {
     }
     if (entity.entityType === 'wellness' || entity.entityType === 'daily_health')
         await importDailyMetrics(database, entity.provider, entity.remoteId, entity.occurredOn, payload, rawHash);
+    if (entity.provider === 'garmin' && entity.entityType === 'body_composition')
+        await importGarminWeight(database, entity.occurredOn, payload, rawHash);
     if (entity.entityType === 'nutrition_day' || entity.entityType === 'nutrition_log')
         await importNutrition(database, entity.provider, entity.occurredOn, entity.remoteId, payload, rawHash);
     if (entity.provider === 'garmin' && entity.entityType === 'training_metric')
@@ -567,6 +570,67 @@ async function importActivityDecoupling(database, provider, remoteId, payload, r
          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 });
     }
 }
+/** Containers searched for provider-supplied run dynamics: the payload itself,
+ * the multisport summary object, common nested analysis/metrics objects, and
+ * the stored metrics_json. Single-activity Garmin payloads carry flat keys;
+ * multisport legs carry the same fields under summaryDTO. */
+function runDynamicsContainers(payload) {
+    const containers = [payload];
+    for (const key of ['summaryDTO', '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;
+}
+const RUN_DYNAMICS_METRICS = [
+    { column: 'vertical_oscillation_cm', keys: ['avgVerticalOscillation', 'verticalOscillation'] },
+    { column: 'ground_contact_time_ms', keys: ['avgGctTime', 'groundContactTime', 'avgGroundContactTime'] },
+    { column: 'flight_time_ms', keys: ['avgFlightTime', 'flightTime'] },
+    { column: 'stride_length_cm', keys: ['avgStrideLength', 'strideLength'] },
+    { column: 'vertical_ratio_pct', keys: ['avgVerticalRatio', 'verticalRatio'] },
+    { column: 'cadence_spm', keys: ['averageRunningCadenceInStepsPerMinute', 'avgRunCadence', 'averageCadence'] },
+];
+function firstReportedNumber(containers, keys) {
+    for (const container of containers) {
+        const found = firstNumber(container, keys);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+/** A5 (persistence): persist provider-supplied running form metrics (vertical
+ * oscillation, ground contact time, flight time, stride length, vertical ratio,
+ * running cadence) so they are queryable across activities instead of only
+ * inside one activity's raw metrics_json. A row is stored only when the payload
+ * reported at least one dynamics value; null columns in a stored row mean the
+ * provider did not report that metric. */
+async function importActivityRunDynamics(database, provider, remoteId, payload, rawHash) {
+    const containers = runDynamicsContainers(payload);
+    const reported = RUN_DYNAMICS_METRICS.map((spec) => firstReportedNumber(containers, spec.keys));
+    if (reported.every((value) => value === null))
+        return;
+    const values = Object.fromEntries(RUN_DYNAMICS_METRICS.map((spec, index) => [spec.column, reported[index]]));
+    const fields = activityFields(provider, payload);
+    await database.run(`INSERT INTO run_dynamics_facts
+      (provider, activity_source_id, sport, started_at_utc, vertical_oscillation_cm, ground_contact_time_ms, flight_time_ms, stride_length_cm, vertical_ratio_pct, cadence_spm, source_type, caveats_json, raw_object_hash)
+     VALUES ($provider, $activitySourceId, $sport, try_cast($startedAtUtc AS TIMESTAMPTZ), $verticalOscillation, $groundContactTime, $flightTime, $strideLength, $verticalRatio, $cadence, 'provider', $caveats, $rawHash)
+     ON CONFLICT (provider, activity_source_id) DO UPDATE SET
+       sport = excluded.sport, started_at_utc = excluded.started_at_utc,
+       vertical_oscillation_cm = excluded.vertical_oscillation_cm, ground_contact_time_ms = excluded.ground_contact_time_ms,
+       flight_time_ms = excluded.flight_time_ms, stride_length_cm = excluded.stride_length_cm,
+       vertical_ratio_pct = excluded.vertical_ratio_pct, cadence_spm = excluded.cadence_spm,
+       source_type = excluded.source_type, caveats_json = excluded.caveats_json, raw_object_hash = excluded.raw_object_hash`, {
+        provider, activitySourceId: providerActivityId(provider, remoteId), sport: fields.sport, startedAtUtc: fields.startAtUtc,
+        verticalOscillation: values.vertical_oscillation_cm, groundContactTime: values.ground_contact_time_ms,
+        flightTime: values.flight_time_ms, strideLength: values.stride_length_cm,
+        verticalRatio: values.vertical_ratio_pct, cadence: values.cadence_spm,
+        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).
@@ -968,6 +1032,64 @@ async function importDailyMetrics(database, provider, remoteId, date, payload, r
     if (provider === 'garmin')
         await importGarminDailyDetails(database, remoteId, metricDate, payload, rawHash);
 }
+/**
+ * Weight-only projection for Garmin weigh-ins. The range endpoint returns
+ * `{dailyWeightSummaries: [{summaryDate, allWeightMetrics: [{weight, ...}]}]}`
+ * with weight in grams, while dayview returns `{dateWeightList: [...]}`.
+ * The worker stages a whole range window as one `body_composition` entity,
+ * so dates are derived per entry here. Multiple weigh-ins on one day resolve
+ * to the latest timestamp. Body-composition fields (fat, muscle, ...) are
+ * deliberately ignored.
+ */
+function weightKgFromValue(value) {
+    if (value === null)
+        return null;
+    return value > 1000 ? value / 1000 : value;
+}
+function weightEntryDate(entry, fallbackDay) {
+    // Prefer the parent summaryDate (Garmin's local day) over the entry's UTC
+    // timestampGMT, which can fall on a different UTC date.
+    return fallbackDay
+        ?? datePart(firstString(entry, ['summaryDate', 'calendarDate', 'date']))
+        ?? datePart(timestamp(entry.timestampGMT));
+}
+function collectGarminWeightEntries(payload, fallbackDay) {
+    const entries = [];
+    const pushEntry = (entry, fallback) => {
+        const kg = weightKgFromValue(firstNumber(entry, ['weight', 'weightValue', 'weightInKg']));
+        if (kg === null)
+            return;
+        const day = weightEntryDate(entry, fallback ?? fallbackDay);
+        if (!day)
+            return;
+        const ts = typeof entry.timestampGMT === 'number' && Number.isFinite(entry.timestampGMT) ? entry.timestampGMT : 0;
+        entries.push({ date: day, kg, ts });
+    };
+    for (const summary of objectArray(payload.dailyWeightSummaries)) {
+        const day = datePart(firstString(summary, ['summaryDate', 'calendarDate', 'date'])) ?? fallbackDay;
+        for (const metric of objectArray(summary.allWeightMetrics))
+            pushEntry(metric, day);
+    }
+    for (const key of ['dateWeightList', 'allWeightMetrics']) {
+        for (const entry of objectArray(payload[key]))
+            pushEntry(entry, fallbackDay);
+    }
+    if (firstNumber(payload, ['weight', 'weightValue', 'weightInKg']) !== null)
+        pushEntry(payload, fallbackDay);
+    return entries;
+}
+async function importGarminWeight(database, date, payload, rawHash) {
+    const fallbackDay = datePart(date);
+    const latestByDay = new Map();
+    for (const entry of collectGarminWeightEntries(payload, fallbackDay)) {
+        const current = latestByDay.get(entry.date);
+        if (!current || entry.ts >= current.ts)
+            latestByDay.set(entry.date, { kg: entry.kg, ts: entry.ts });
+    }
+    for (const [metricDate, { kg }] of latestByDay) {
+        await upsertDailyMetric(database, 'garmin', metricDate, 'weight_kg', kg, null, 'kg', rawHash);
+    }
+}
 async function importNutrition(database, provider, date, remoteId, payload, rawHash) {
     const nutritionDate = datePart(date) ?? datePart(firstString(payload, ['id', 'date', 'calendarDate'])) ?? null;
     if (!nutritionDate)

package/dist/elt/storage/migrations.js

@@ -972,5 +972,49 @@ const activityDecouplingFactsMigration = {
     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];
+const runDynamicsFactsMigration = {
+    version: 18,
+    name: 'run_dynamics_facts',
+    sql: `
+    -- A5 (persistence): make provider-supplied running dynamics queryable
+    -- historically instead of only inside one activity's raw metrics_json.
+    -- Values are provider-normalized running form metrics; a null column means
+    -- the provider did not report that metric for the activity. Only activities
+    -- with at least one reported value get a row. Single activities carry the
+    -- fields flat; multisport legs carry them nested under summaryDTO, and the
+    -- normalizer searches both shapes. Rows are written by the activity
+    -- normalizer on import (matching activity_decoupling, with no SQL backfill),
+    -- so previously imported activities gain rows when their source entity is
+    -- refreshed or re-imported; the upsert is idempotent.
+    CREATE TABLE IF NOT EXISTS run_dynamics_facts (
+      provider VARCHAR NOT NULL,
+      activity_source_id VARCHAR NOT NULL,
+      sport VARCHAR,
+      started_at_utc TIMESTAMPTZ,
+      vertical_oscillation_cm DOUBLE,
+      ground_contact_time_ms DOUBLE,
+      flight_time_ms DOUBLE,
+      stride_length_cm DOUBLE,
+      vertical_ratio_pct DOUBLE,
+      cadence_spm DOUBLE,
+      source_type VARCHAR NOT NULL,
+      caveats_json JSON,
+      raw_object_hash VARCHAR,
+      PRIMARY KEY (provider, activity_source_id)
+    );
+
+    -- Join view so callers can filter or group by logical activity without
+    -- hand-joining activity_sources/activities. Every facts row is current by
+    -- construction (the primary key is the source row), so no ranking filter is
+    -- applied and provider rows are never hidden.
+    CREATE OR REPLACE VIEW run_dynamics AS
+    SELECT facts.*, source.activity_id, source.remote_activity_id, activity.name
+    FROM run_dynamics_facts AS facts
+    JOIN activity_sources AS source USING (activity_source_id)
+    JOIN activities AS activity USING (activity_id);
+
+    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, runDynamicsFactsMigration];
 //# sourceMappingURL=migrations.js.map

package/dist/elt/storage/progress-sidecar.d.ts

@@ -48,7 +48,16 @@ export declare class ProgressPump {
     private lastHeartbeatAt;
     private interval;
     private stageOverride;
+    /**
+     * Serializes heartbeat writes in call order. publish() used to fire its
+     * database and sidecar writes without awaiting them, so a throttled write
+     * could win the sidecar rename race against a later publishFinal() and
+     * leave a stale non-terminal stage behind.
+     */
+    private writeTail;
     constructor(runId: string, provider: string, options: ProgressPumpOptions);
+    private enqueueHeartbeat;
+    private writeHeartbeat;
     start(): void;
     publish(state: SyncProgressState): void;
     /** Force subsequent keep-alive heartbeats to report the given stage. */

package/dist/elt/storage/progress-sidecar.js

@@ -133,11 +133,36 @@ export class ProgressPump {
     lastHeartbeatAt = 0;
     interval = null;
     stageOverride = null;
+    /**
+     * Serializes heartbeat writes in call order. publish() used to fire its
+     * database and sidecar writes without awaiting them, so a throttled write
+     * could win the sidecar rename race against a later publishFinal() and
+     * leave a stale non-terminal stage behind.
+     */
+    writeTail = Promise.resolve();
     constructor(runId, provider, options) {
         this.runId = runId;
         this.provider = provider;
         this.options = options;
     }
+    enqueueHeartbeat(state) {
+        const run = this.writeTail.then(() => this.writeHeartbeat(state));
+        // A write failure is already logged inside writeHeartbeat; never let it
+        // break the chain (or surface as an unhandled rejection) for later beats.
+        this.writeTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async writeHeartbeat(state) {
+        const { database, paths, log } = this.options;
+        await Promise.all([
+            database.heartbeatRun(this.runId, state).catch((error) => {
+                log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+            }),
+            writeProgressSidecar(paths, this.runId, state).catch((error) => {
+                log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+            }),
+        ]);
+    }
     start() {
         if (this.interval)
             return;
@@ -156,13 +181,7 @@ export class ProgressPump {
         }
         this.lastHeartbeatAt = now;
         this.lastProgress = state;
-        const { database, paths, log } = this.options;
-        void database.heartbeatRun(this.runId, state).catch((error) => {
-            log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
-        void writeProgressSidecar(paths, this.runId, state).catch((error) => {
-            log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
+        void this.enqueueHeartbeat(state).catch(() => undefined);
     }
     /** Force subsequent keep-alive heartbeats to report the given stage. */
     setStage(stage) {
@@ -180,15 +199,11 @@ export class ProgressPump {
     async publishFinal(state) {
         this.lastHeartbeatAt = Date.now();
         this.lastProgress = state;
-        const { database, paths, log } = this.options;
-        // Both terminal writes complete before the caller removes the sidecar, so
-        // a finished run can never resurrect its own progress file after cleanup.
-        await database.heartbeatRun(this.runId, state).catch((error) => {
-            log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
-        await writeProgressSidecar(paths, this.runId, state).catch((error) => {
-            log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
+        // Awaiting the chained write guarantees every earlier heartbeat (in
+        // particular a throttled publish still in flight) lands first, so the
+        // terminal stage is always the last one persisted before the caller
+        // removes the sidecar.
+        await this.enqueueHeartbeat(state);
     }
     stop() {
         if (this.interval) {

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, 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';
+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, reimportWeight, 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.')
@@ -256,6 +256,10 @@ program.command('reimport-nutrition').description('Re-run normalization over cap
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await reimportNutrition(paths), null, 2)}\n`);
 });
+program.command('reimport-weight').description('Backfill weight_kg from captured Garmin weigh-in entities without contacting providers.').action(async () => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await reimportWeight(paths), null, 2)}\n`);
+});
 program
     .command('import')
     .description('Import a staged JSONL file (for example a swim-length backfill) into one athlete’s data store.')

package/dist/interfaces/http/server.js

@@ -1,7 +1,7 @@
 import { createServer } from 'node:http';
 import path from 'node:path';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { catenceRuntimeHealth, DashboardSnapshotService, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, resolveAthlete, resolveCatalogPaths, startDetachedSync, syncProgress, } from '../../runtime/index.js';
+import { addAthlete, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, catenceRuntimeHealth, DashboardSnapshotService, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, listAthleteFileRevisions, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, readAthleteFile, readAthleteFileRevision, resolveAthlete, resolveCatalogPaths, startDetachedSync, syncProgress, updateAthleteFile, } from '../../runtime/index.js';
 import { createCatenceMcpServer } from '../mcp/server.js';
 import { generationStatus } from './generation-status.js';
 const MAX_REQUEST_BYTES = 1_000_000;
@@ -18,8 +18,8 @@ function addCorsHeaders(request, response, allowedOrigins) {
         return false;
     response.setHeader('access-control-allow-origin', origin);
     response.setHeader('vary', 'Origin');
-    response.setHeader('access-control-allow-methods', 'GET, POST, DELETE, OPTIONS');
-    response.setHeader('access-control-allow-headers', 'content-type, mcp-session-id');
+    response.setHeader('access-control-allow-methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    response.setHeader('access-control-allow-headers', 'content-type, if-match, mcp-session-id');
     return true;
 }
 async function readJsonBody(request) {
@@ -112,6 +112,49 @@ function parseSyncBody(body) {
     }
     return raw;
 }
+function parseAthleteCreateBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['id', 'label', 'setDefault'].includes(key))
+            throw new Error(`Unknown athlete field: ${key}.`);
+    }
+    if (typeof raw.id !== 'string' || !raw.id.trim())
+        throw new Error('id is required.');
+    if (typeof raw.label !== 'string' || !raw.label.trim())
+        throw new Error('label is required.');
+    if (raw.setDefault !== undefined && typeof raw.setDefault !== 'boolean')
+        throw new Error('setDefault must be a boolean.');
+    return { id: raw.id.trim(), label: raw.label.trim(), setDefault: raw.setDefault === true };
+}
+function parseAthleteFileBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['operation', 'section', 'content', 'expectedHash'].includes(key))
+            throw new Error(`Unknown athlete-file field: ${key}.`);
+    }
+    if (typeof raw.content !== 'string')
+        throw new Error('content must be a string.');
+    const operation = raw.operation ?? 'replace';
+    if (operation !== 'replace' && operation !== 'append' && operation !== 'replace_section') {
+        throw new Error('operation must be replace, append, or replace_section.');
+    }
+    if (raw.section !== undefined && typeof raw.section !== 'string')
+        throw new Error('section must be a string.');
+    if (raw.expectedHash !== undefined && raw.expectedHash !== null && typeof raw.expectedHash !== 'string') {
+        throw new Error('expectedHash must be a string or null.');
+    }
+    return {
+        operation,
+        section: raw.section,
+        content: raw.content,
+        hasExpectedHash: Object.prototype.hasOwnProperty.call(raw, 'expectedHash'),
+        expectedHash: (raw.expectedHash ?? null),
+    };
+}
 async function resolveSyncPaths(catalogPaths, staticPaths, body) {
     if (catalogPaths) {
         if (!body.athleteId)
@@ -258,6 +301,33 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/athletes' && request.method === 'POST') {
+                if (!catalogPaths) {
+                    json(response, 400, {
+                        error: {
+                            code: 'catalog_required',
+                            message: 'Adding athletes requires a Catence catalog; this server uses a single legacy data store.',
+                        },
+                    });
+                    return;
+                }
+                try {
+                    const body = parseAthleteCreateBody(await readJsonBody(request));
+                    const catalog = await loadCatalog(catalogPaths);
+                    if (catalog.athletes.some((athlete) => athlete.id === body.id)) {
+                        json(response, 409, { error: { code: 'athlete_exists', message: `Athlete ${body.id} already exists.` } });
+                        return;
+                    }
+                    const updated = await addAthlete(catalogPaths, body);
+                    json(response, 201, { defaultAthleteId: updated.defaultAthleteId, athletes: updated.athletes });
+                }
+                catch (error) {
+                    json(response, 400, {
+                        error: { code: 'athlete_create_failed', message: error instanceof Error ? error.message : String(error) },
+                    });
+                }
+                return;
+            }
             if (pathname === '/api/v1/dashboard' && request.method === 'GET') {
                 try {
                     const url = new URL(request.url ?? '/', 'http://localhost');
@@ -268,6 +338,74 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/athlete-file' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url);
+                    const revisionId = url.searchParams.get('revision');
+                    if (revisionId) {
+                        let content;
+                        try {
+                            content = await readAthleteFileRevision(paths, revisionId);
+                        }
+                        catch (error) {
+                            if (!(error instanceof AthleteFileValidationError))
+                                throw error;
+                            content = null;
+                        }
+                        if (content === null) {
+                            json(response, 404, { error: { code: 'athlete_file_revision_not_found', message: 'No athlete-file revision matches this identifier.' } });
+                            return;
+                        }
+                        json(response, 200, { revisionId, content });
+                        return;
+                    }
+                    const snapshot = await readAthleteFile(paths);
+                    json(response, 200, { ...snapshot, revisions: await listAthleteFileRevisions(paths) });
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'athlete_file_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/athlete-file' && request.method === 'PUT') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url);
+                    const parsed = parseAthleteFileBody(await readJsonBody(request));
+                    const header = request.headers['if-match'];
+                    const headerHash = typeof header === 'string' && header.trim() ? header.trim() : undefined;
+                    if (!headerHash && !parsed.hasExpectedHash) {
+                        throw new AthleteFileValidationError('expectedHash is required: send the If-Match header or the expectedHash body field (null to create the file).');
+                    }
+                    const snapshot = await updateAthleteFile(paths, {
+                        operation: parsed.operation,
+                        section: parsed.section,
+                        content: parsed.content,
+                        expectedHash: headerHash ?? parsed.expectedHash,
+                    });
+                    json(response, 200, snapshot);
+                }
+                catch (error) {
+                    if (error instanceof AthleteFileConflictError) {
+                        json(response, 409, {
+                            error: {
+                                code: 'athlete_file_conflict',
+                                message: error.message,
+                                currentHash: error.currentHash,
+                                currentContent: error.currentContent,
+                            },
+                        });
+                    }
+                    else if (error instanceof AthleteFileTooLargeError || error instanceof AthleteFileValidationError) {
+                        json(response, 400, { error: { code: 'invalid_request', message: error.message } });
+                    }
+                    else {
+                        json(response, 400, { error: { code: 'athlete_file_write_failed', message: error instanceof Error ? error.message : String(error) } });
+                    }
+                }
+                return;
+            }
             if (pathname === '/api/v1/sync' && request.method === 'POST') {
                 let body;
                 try {