catence 0.2.0-beta.1 → 0.2.0-beta.11

package/dist/elt/storage/database.js

@@ -2,6 +2,7 @@ import { DuckDBInstance } from '@duckdb/node-api';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { ReadOnlyRepository } from '../../core/query/repository.js';
+import { SYNC_STAGES, STALE_RUN_TIMEOUT_MS } from '../../contracts/progress.js';
 import { migrations } from './migrations.js';
 import { json } from './sql.js';
 export class CatenceDatabase {
@@ -81,6 +82,66 @@ export class CatenceDatabase {
         await this.run(`UPDATE sync_runs SET status = CASE WHEN error_count > 0 THEN 'completed_with_errors' ELSE 'completed' END, completed_at = now() WHERE run_id = $runId`, { runId });
         await this.run("UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context'");
     }
+    async heartbeatRun(runId, progress) {
+        await this.run(`INSERT INTO sync_run_progress (run_id, provider, stage, current_step, completed_units, total_units, percent, elapsed_seconds, estimated_remaining_seconds, heartbeat_at, detail_json)
+       VALUES ($runId, $provider, $stage, $currentStep, $completedUnits, $totalUnits, $percent, $elapsedSeconds, $estimatedRemainingSeconds, now(), '{}')
+       ON CONFLICT (run_id) DO UPDATE SET
+         provider = EXCLUDED.provider,
+         stage = EXCLUDED.stage,
+         current_step = EXCLUDED.current_step,
+         completed_units = EXCLUDED.completed_units,
+         total_units = EXCLUDED.total_units,
+         percent = EXCLUDED.percent,
+         elapsed_seconds = EXCLUDED.elapsed_seconds,
+         estimated_remaining_seconds = EXCLUDED.estimated_remaining_seconds,
+         heartbeat_at = now(),
+         detail_json = '{}'`, {
+            runId,
+            provider: progress.provider,
+            stage: progress.stage,
+            currentStep: progress.currentStep,
+            completedUnits: progress.completedUnits,
+            totalUnits: progress.totalUnits,
+            percent: progress.percentComplete,
+            elapsedSeconds: progress.elapsedSeconds,
+            estimatedRemainingSeconds: progress.estimatedRemainingSeconds,
+        });
+    }
+    async markRunInterrupted(runId, stage = 'interrupted') {
+        await this.run("UPDATE sync_runs SET status = 'interrupted', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId });
+        await this.run('UPDATE sync_run_progress SET stage = $stage, heartbeat_at = now() WHERE run_id = $runId', { runId, stage });
+    }
+    async interruptStaleSyncRuns(timeoutMs = STALE_RUN_TIMEOUT_MS) {
+        const cutoff = new Date(Date.now() - timeoutMs).toISOString();
+        const stale = await this.rows(`SELECT run_id FROM sync_runs WHERE status = 'running' AND started_at < $cutoff`, { cutoff });
+        for (const row of stale) {
+            await this.run("UPDATE sync_runs SET status = 'timed_out', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId: row.run_id });
+            await this.run("UPDATE sync_run_progress SET stage = 'timed_out', heartbeat_at = now() WHERE run_id = $runId", { runId: row.run_id });
+        }
+        return { runIds: stale.map((row) => row.run_id) };
+    }
+    async syncProgress() {
+        const running = await this.rows(`SELECT runs.run_id, runs.provider,
+         coalesce(progress.stage, 'starting') AS stage,
+         progress.current_step AS current_step,
+         coalesce(progress.completed_units, 0) AS completed_units,
+         progress.total_units AS total_units,
+         coalesce(progress.percent, 0) AS percent,
+         coalesce(progress.elapsed_seconds, 0) AS elapsed_seconds,
+         progress.estimated_remaining_seconds AS estimated_remaining_seconds,
+         cast(coalesce(progress.heartbeat_at, runs.started_at) AS VARCHAR) AS heartbeat_at
+       FROM sync_runs AS runs
+       LEFT JOIN sync_run_progress AS progress USING (run_id)
+       WHERE runs.status = 'running'
+       ORDER BY runs.started_at DESC`);
+        const recent = await this.rows(`SELECT progress.run_id, progress.provider, progress.stage, progress.current_step,
+         progress.completed_units, progress.total_units, progress.percent, progress.elapsed_seconds,
+         progress.estimated_remaining_seconds, cast(progress.heartbeat_at AS VARCHAR) AS heartbeat_at
+       FROM sync_run_progress AS progress
+       ORDER BY progress.heartbeat_at DESC
+       LIMIT 10`);
+        return { running: running.map(toSyncProgressState), recent: recent.map(toSyncProgressState) };
+    }
     async addError(runId, provider, endpoint, remoteId, message, retryable) {
         await this.run(`INSERT INTO normalization_errors (error_id, run_id, provider, endpoint, remote_id, message, retryable)
        VALUES ($errorId, $runId, $provider, $endpoint, $remoteId, $message, $retryable)`, { errorId: randomUUID(), runId, provider, endpoint, remoteId, message, retryable });
@@ -94,9 +155,11 @@ export class CatenceDatabase {
         const rawObjects = await this.rows('SELECT count(*)::INTEGER AS count FROM raw_objects');
         const activities = await this.rows('SELECT count(*)::INTEGER AS count FROM activities');
         const streams = await this.rows('SELECT count(*)::INTEGER AS count FROM stream_manifest');
+        const errorDetails = await this.rows('SELECT run_id, provider, endpoint, remote_id, message, cast(created_at AS VARCHAR) AS created_at FROM normalization_errors WHERE resolved_at IS NULL ORDER BY created_at DESC LIMIT 100');
         const cursors = await this.rows('SELECT provider, cursor_name, cast(covered_through_date AS VARCHAR) AS covered_through_date, cast(latest_source_date AS VARCHAR) AS latest_source_date, lookback_days, last_successful_run_id, cast(last_completed_at AS VARCHAR) AS last_completed_at, status FROM sync_cursors ORDER BY provider, cursor_name');
         return {
             runs, unresolvedErrors: errors[0]?.count ?? 0, rawObjects: rawObjects[0]?.count ?? 0, activities: activities[0]?.count ?? 0, streams: streams[0]?.count ?? 0,
+            errors: errorDetails,
             cursors: cursors.map((cursor) => ({ ...cursor, next_from_date: subtractDays(cursor.covered_through_date, Number(cursor.lookback_days)) })),
         };
     }
@@ -281,10 +344,6 @@ export class ReadOnlyCatenceDatabase {
         }
     }
 }
-/** Compose core read services with the DuckDB-backed, read-only adapter. */
-export async function openReadOnlyRepository(paths) {
-    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
-}
 export class ReadOnlyDatabaseError extends Error {
     code;
     constructor(code, message) {
@@ -293,4 +352,22 @@ export class ReadOnlyDatabaseError extends Error {
         this.name = 'ReadOnlyDatabaseError';
     }
 }
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export async function openReadOnlyRepository(paths) {
+    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
+}
+function toSyncProgressState(row) {
+    return {
+        runId: row.run_id,
+        provider: row.provider,
+        stage: SYNC_STAGES.includes(row.stage) ? row.stage : 'starting',
+        currentStep: row.current_step,
+        completedUnits: Math.max(0, Number(row.completed_units) || 0),
+        totalUnits: row.total_units === null || row.total_units === undefined ? null : Math.max(0, Number(row.total_units) || 0),
+        percentComplete: Math.min(100, Math.max(0, Number(row.percent) || 0)),
+        elapsedSeconds: Math.max(0, Number(row.elapsed_seconds) || 0),
+        estimatedRemainingSeconds: row.estimated_remaining_seconds === null || row.estimated_remaining_seconds === undefined ? null : Math.max(0, Number(row.estimated_remaining_seconds) || 0),
+        heartbeatAt: row.heartbeat_at,
+    };
+}
 //# sourceMappingURL=database.js.map

package/dist/elt/storage/migrations.js

@@ -828,5 +828,29 @@ const swimFactsAndQualityMigration = {
     UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
   `,
 };
-export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration];
+const syncRunProgressMigration = {
+    version: 14,
+    name: 'sync_run_progress_heartbeats',
+    sql: `
+    -- Live progress heartbeats for in-flight sync runs. Written by the Node
+    -- side from progress records streamed by provider workers; read-only
+    -- surfaces (status, progress CLI, MCP) join against sync_runs.
+    CREATE TABLE IF NOT EXISTS sync_run_progress (
+      run_id VARCHAR PRIMARY KEY,
+      provider VARCHAR NOT NULL,
+      stage VARCHAR NOT NULL,
+      current_step VARCHAR,
+      completed_units INTEGER NOT NULL DEFAULT 0,
+      total_units INTEGER,
+      percent DOUBLE NOT NULL DEFAULT 0,
+      elapsed_seconds DOUBLE NOT NULL DEFAULT 0,
+      estimated_remaining_seconds DOUBLE,
+      heartbeat_at TIMESTAMPTZ NOT NULL,
+      detail_json JSON NOT NULL DEFAULT '{}'
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration];
 //# sourceMappingURL=migrations.js.map

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

@@ -0,0 +1,26 @@
+import { type SyncProgressSnapshot, type SyncProgressState } from '../../contracts/progress.js';
+import type { CatencePaths } from '../../contracts/runtime.js';
+export declare const PROGRESS_SIDECAR_SUFFIX = ".progress.json";
+export declare const PROGRESS_SIDECAR_STALE_MS: number;
+export declare function progressSidecarPath(paths: CatencePaths, runId: string): string;
+/**
+ * Persist one progress heartbeat as a sidecar file next to the Garmin staging
+ * manifest. Reading this file needs no DuckDB lock, so `progress` stays live
+ * while a sync run holds the single-writer database lock.
+ */
+export declare function writeProgressSidecar(paths: CatencePaths, runId: string, state: SyncProgressState): Promise<void>;
+export declare function removeProgressSidecar(paths: CatencePaths, runId: string): Promise<void>;
+/**
+ * Scan every persisted sidecar heartbeat for an athlete store. Corrupt or
+ * unreadable files are skipped so a torn write can never break progress reads.
+ */
+export declare function readProgressSidecars(paths: CatencePaths): Promise<SyncProgressState[]>;
+/** Active runs from sidecars: non-terminal stage and a fresh heartbeat. */
+export declare function readRunningProgress(paths: CatencePaths, staleAfterMs?: number): Promise<SyncProgressState[]>;
+/**
+ * Merge database-backed progress with sidecar heartbeats. Sidecars win for a
+ * given run (they are freshest); database rows fill runs that never emitted a
+ * sidecar (for example Intervals runs). Recent history is deduplicated across
+ * both sources and sorted by heartbeat recency.
+ */
+export declare function mergeProgress(dbRunning: SyncProgressState[], dbRecent: SyncProgressState[], sidecars: SyncProgressState[]): SyncProgressSnapshot;

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

@@ -0,0 +1,87 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeProgress } from '../../contracts/progress.js';
+export const PROGRESS_SIDECAR_SUFFIX = '.progress.json';
+export const PROGRESS_SIDECAR_STALE_MS = 5 * 60 * 1000;
+const TERMINAL_STAGES = new Set(['completed', 'failed', 'interrupted', 'timed_out']);
+export function progressSidecarPath(paths, runId) {
+    return path.join(paths.staging, 'garmin', `${runId}${PROGRESS_SIDECAR_SUFFIX}`);
+}
+/**
+ * Persist one progress heartbeat as a sidecar file next to the Garmin staging
+ * manifest. Reading this file needs no DuckDB lock, so `progress` stays live
+ * while a sync run holds the single-writer database lock.
+ */
+export async function writeProgressSidecar(paths, runId, state) {
+    const target = progressSidecarPath(paths, runId);
+    await mkdir(path.dirname(target), { recursive: true });
+    const temporary = `${target}.tmp`;
+    await writeFile(temporary, JSON.stringify(state));
+    await rename(temporary, target);
+}
+export async function removeProgressSidecar(paths, runId) {
+    await rm(progressSidecarPath(paths, runId), { force: true });
+}
+/**
+ * Scan every persisted sidecar heartbeat for an athlete store. Corrupt or
+ * unreadable files are skipped so a torn write can never break progress reads.
+ */
+export async function readProgressSidecars(paths) {
+    const directory = path.join(paths.staging, 'garmin');
+    if (!existsSync(directory))
+        return [];
+    const files = (await readdir(directory)).filter((file) => file.endsWith(PROGRESS_SIDECAR_SUFFIX));
+    const states = [];
+    for (const file of files) {
+        try {
+            const state = normalizeProgress(JSON.parse(await readFile(path.join(directory, file), 'utf8')));
+            if (state)
+                states.push(state);
+        }
+        catch {
+            // Torn or partial sidecar write; it is not authoritative.
+        }
+    }
+    return states;
+}
+/** Active runs from sidecars: non-terminal stage and a fresh heartbeat. */
+export async function readRunningProgress(paths, staleAfterMs = PROGRESS_SIDECAR_STALE_MS) {
+    const now = Date.now();
+    const running = [];
+    for (const state of await readProgressSidecars(paths)) {
+        if (TERMINAL_STAGES.has(state.stage))
+            continue;
+        const ageMs = now - Date.parse(state.heartbeatAt);
+        if (!Number.isFinite(ageMs) || ageMs > staleAfterMs)
+            continue;
+        running.push(state);
+    }
+    return running;
+}
+/**
+ * Merge database-backed progress with sidecar heartbeats. Sidecars win for a
+ * given run (they are freshest); database rows fill runs that never emitted a
+ * sidecar (for example Intervals runs). Recent history is deduplicated across
+ * both sources and sorted by heartbeat recency.
+ */
+export function mergeProgress(dbRunning, dbRecent, sidecars) {
+    const running = new Map();
+    for (const state of sidecars)
+        running.set(state.runId, state);
+    for (const state of dbRunning)
+        if (!running.has(state.runId))
+            running.set(state.runId, state);
+    const recent = new Map();
+    for (const state of dbRecent)
+        recent.set(state.runId, state);
+    for (const state of sidecars)
+        recent.set(state.runId, state);
+    return {
+        running: [...running.values()],
+        recent: [...recent.values()]
+            .sort((a, b) => Date.parse(b.heartbeatAt) - Date.parse(a.heartbeatAt))
+            .slice(0, 10),
+    };
+}
+//# sourceMappingURL=progress-sidecar.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, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, initializeCatalog, linkActivity, loadCatalog, rebuildRetrievalIndex, resolveAthlete, resolveCatalogPaths, retryDataSync, setAthleteSecret, syncData, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, 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.')
@@ -158,6 +158,96 @@ program.command('status').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await dataStatus(paths), null, 2)}\n`);
 });
+function renderProgress(snapshot) {
+    const lines = snapshot.running.map((run) => {
+        const pct = run.percentComplete.toFixed(1).padStart(5);
+        const units = run.totalUnits !== null ? `${run.completedUnits}/${run.totalUnits}` : String(run.completedUnits);
+        const eta = run.estimatedRemainingSeconds !== null ? `${Math.round(run.estimatedRemainingSeconds)}s` : '?';
+        const step = run.currentStep ?? '';
+        return `${pct}%  ${run.stage.padEnd(12)} ${units.padEnd(11)} ${eta.padEnd(6)} ${step}`;
+    });
+    return lines.length === 0 ? 'no active sync runs' : lines.join('\n');
+}
+program.command('progress')
+    .description('Show live progress for active sync runs.')
+    .option('--watch', 'refresh every few seconds until no sync runs are active')
+    .action(async (options) => {
+    const { paths } = await currentAthlete();
+    if (!options.watch) {
+        process.stdout.write(`${JSON.stringify(await syncProgress(paths), null, 2)}\n`);
+        return;
+    }
+    while (true) {
+        const snapshot = await syncProgress(paths);
+        if (output.isTTY) {
+            output.write(`\x1b[2J\x1b[H${renderProgress(snapshot)}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+        }
+        if (snapshot.running.length === 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+});
+program.command('update')
+    .description('Check for and apply the newest Catence release on the tracked channel (runtime and Console).')
+    .option('--check', 'report available releases without changing anything')
+    .option('--channel <stable|beta>', 'release channel to track; defaults to the installed runtime channel')
+    .option('--runtime', 'only check or update the Catence runtime package')
+    .option('--console', 'only check or update the Catence Console package')
+    .action(async (options) => {
+    if (options.channel !== undefined && options.channel !== 'stable' && options.channel !== 'beta') {
+        throw new Error('--channel must be stable or beta.');
+    }
+    const channel = options.channel ?? channelForVersion(CATENCE_RUNTIME_VERSION);
+    const runtimeOnly = options.runtime ?? false;
+    const consoleOnly = options.console ?? false;
+    const updateRuntime = runtimeOnly || !consoleOnly;
+    const updateConsole = consoleOnly || !runtimeOnly;
+    const [npmDistTags, pypiReleases, consoleInstalled] = await Promise.all([
+        fetchNpmDistTags('catence'),
+        fetchPypiReleases('catence-console'),
+        readInstalledConsoleVersion(),
+    ]);
+    const plan = planSelfUpdate({ runtimeVersion: CATENCE_RUNTIME_VERSION, channel, npmDistTags, pypiReleases, consoleInstalled });
+    const report = { channel, runtime: plan.runtime, console: plan.console };
+    if (options.check) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        process.exit(plan.ok ? 0 : 1);
+    }
+    const applied = [];
+    if (plan.runtime.updateAvailable && updateRuntime) {
+        const runtimeTarget = plan.runtime.target;
+        if (runtimeTarget === undefined)
+            throw new Error('No runtime update target is available.');
+        const npmPrefix = await npmGlobalPrefix();
+        if (isGlobalNpmInstall(import.meta.url, npmPrefix)) {
+            const exitCode = await runSelfUpdateCommand('npm', ['install', '--global', `catence@${runtimeTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`npm failed to install catence@${runtimeTarget} (exit ${exitCode}).`);
+            applied.push(`runtime: catence@${runtimeTarget}`);
+        }
+        else {
+            process.stderr.write(`Runtime is not a global npm install; run: npm install --global catence@${runtimeTarget}\n`);
+        }
+    }
+    if (plan.console.updateAvailable && updateConsole) {
+        const consoleTarget = plan.console.target;
+        if (consoleTarget === undefined)
+            throw new Error('No Console update target is available.');
+        if (await hasCommand('uv')) {
+            const exitCode = await runSelfUpdateCommand('uv', ['tool', 'install', '--upgrade', `catence-console==${consoleTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`uv failed to install catence-console==${consoleTarget} (exit ${exitCode}).`);
+            applied.push(`console: catence-console==${consoleTarget}`);
+        }
+        else {
+            process.stderr.write(`uv is not installed; run: pip install --upgrade 'catence-console==${consoleTarget}'\n`);
+        }
+    }
+    process.stdout.write(`${JSON.stringify({ ...report, applied }, null, 2)}\n`);
+});
 program.command('build-retrieval-index').description('Build derived local retrieval context for one athlete.').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await rebuildRetrievalIndex(paths), null, 2)}\n`);

package/dist/interfaces/mcp/server.js

@@ -231,6 +231,13 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         data: { ...(await repository.status()), ...(await repository.coverage()) },
         provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
     }))));
+    server.registerTool('catence_sync_progress', {
+        title: 'Catence sync progress',
+        description: 'Read live progress heartbeats for active sync runs, plus the most recent completed or interrupted runs. Read-only.',
+    }, tool('catence_sync_progress', async () => useRepository(activePaths(), async (repository) => ({
+        data: await repository.progress(),
+        provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
+    }))));
     server.registerTool('review_daily_recovery_load', {
         title: 'Review daily recovery and training load',
         description: 'Return source-cited daily health, training, and nutrition facts for a recovery/load review. It does not prescribe a training plan.',

package/dist/runtime/index.d.ts

@@ -7,6 +7,8 @@
  * without changing the public product adapters.
  */
 export type { CatencePaths } from '../contracts/runtime.js';
+export { channelForVersion, compareReleaseVersions, fetchNpmDistTags, fetchPypiReleases, hasCommand, isGlobalNpmInstall, latestRelease, npmGlobalPrefix, parseReleaseVersion, planSelfUpdate, readInstalledConsoleVersion, runSelfUpdateCommand, } from '../core/runtime/self-update.js';
+export type { SelfUpdatePlan, UpdateChannel } from '../core/runtime/self-update.js';
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
@@ -26,8 +28,9 @@ export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
+export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export type { ProviderChoice } from '../elt/application/management.js';
+export type { InterruptedRuns, SyncProgressSnapshot, SyncProgressState } from '../contracts/progress.js';
 export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/dist/runtime/index.js

@@ -1,3 +1,4 @@
+export { channelForVersion, compareReleaseVersions, fetchNpmDistTags, fetchPypiReleases, hasCommand, isGlobalNpmInstall, latestRelease, npmGlobalPrefix, parseReleaseVersion, planSelfUpdate, readInstalledConsoleVersion, runSelfUpdateCommand, } from '../core/runtime/self-update.js';
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
@@ -14,7 +15,7 @@ export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
+export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/docs/architecture.md

@@ -87,7 +87,17 @@ The query layer has four shared pieces:
 
 ### 4. Serving and retrieval
 
-The server exposes `catence_status`, `describe_data`, `describe_dataset`, `read_series`, `aggregate_data`, `analyze_series`, `fit_series_model`, `query_read_only_data`, `find_activities`, `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, `power_coverage_report`, `latest_cycling_activities`, `cycling_progress_report`, `review_daily_recovery_load`, `review_weekly_training`, `review_activity_deep_dive`, `search_context`, `hydrate_strava_activity`, `hydrate_recent_strava_activities`, and `hydrate_strava_segment_history`, plus resources for status, catalog, a single activity, and a date-range summary.
+The server exposes these tools, grouped by purpose:
+
+- Catalog and status: `list_athletes`, `catence_status`, `catence_sync_progress`.
+- Review workflows: `review_daily_recovery_load`, `review_weekly_training`, `review_activity_deep_dive`, plus the matching `daily_recovery_load_review`, `weekly_training_review`, and `activity_deep_dive` prompts.
+- General data and analytics: `describe_data`, `describe_dataset`, `read_series`, `aggregate_data`, `analyze_series`, `fit_series_model`, `query_read_only_data`, `search_context`.
+- Wellness: `wellness_correlate`, `wellness_baselines`, `wellness_anomalies`, `wellness_coverage`.
+- Fitness and progress: `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, `power_coverage_report`, `latest_cycling_activities`, `cycling_progress_report`, `get_swim_laps`, `swim_progress_report`.
+- Activity detail and segments: `find_activities`, `get_activity_segments`.
+- Strava hydration (the only writers): `hydrate_strava_activity`, `hydrate_recent_strava_activities`, `hydrate_strava_segment_history`.
+
+Resources are mode-dependent. In catalog mode the server registers only `athletes` (`catence://athletes`), the machine-readable roster of configured athlete IDs and labels; in a single-store (non-catalog) deployment it registers resources for status, catalog, a single activity template (`catence://activity/{activityId}`), and a date-range summary template (`catence://summary/{startDate}/{endDate}`).
 
 `catence serve` is a loopback-only-by-default Streamable HTTP adapter. It creates a stateless MCP server and transport for each `/mcp` request, so the HTTP and stdio surfaces use the same tool implementation. `GET /health` is a versioned client handshake with runtime version, protocol version, and capabilities; distributed Console builds reject an incompatible protocol before starting a chat. The same listener serves a small read-only `/api/v1/dashboard` snapshot for the local Console: canonical daily-health rows, weekly canonical activity aggregates, recent canonical activities, status, coverage, and explicit missing-data caveats.