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

package/dist/core/runtime/self-update.js

@@ -0,0 +1,138 @@
+/**
+ * Self-update support for the Catence runtime and its Console.
+ *
+ * The runtime tracks npm dist-tags on the `catence` package; the Console
+ * tracks PEP 440 releases on PyPI (`catence-console`). A release is "newer"
+ * only when it strictly dominates the installed version inside the tracked
+ * channel: `stable` for non-prerelease installs, or the beta prerelease
+ * channel for beta installs. Channel names match npm dist-tags, so a beta
+ * runtime consults the `beta` tag and an explicit `--channel stable` moves a
+ * beta install onto the `latest` tag.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const NPM_VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/;
+const PEP440_BETA = /^(\d+)\.(\d+)\.(\d+)b(\d+)$/;
+export function parseReleaseVersion(version) {
+    const npm = NPM_VERSION.exec(version.trim());
+    if (npm) {
+        return {
+            major: Number(npm[1]),
+            minor: Number(npm[2]),
+            patch: Number(npm[3]),
+            beta: npm[4] === undefined ? undefined : Number(npm[4]),
+        };
+    }
+    const pep440 = PEP440_BETA.exec(version.trim());
+    if (pep440) {
+        return { major: Number(pep440[1]), minor: Number(pep440[2]), patch: Number(pep440[3]), beta: Number(pep440[4]) };
+    }
+    return null;
+}
+export function compareReleaseVersions(left, right) {
+    for (const field of ['major', 'minor', 'patch']) {
+        if (left[field] !== right[field])
+            return left[field] < right[field] ? -1 : 1;
+    }
+    const leftBeta = left.beta ?? Number.POSITIVE_INFINITY;
+    const rightBeta = right.beta ?? Number.POSITIVE_INFINITY;
+    if (leftBeta === rightBeta)
+        return 0;
+    return leftBeta < rightBeta ? -1 : 1;
+}
+export function channelForVersion(version) {
+    return parseReleaseVersion(version)?.beta !== undefined ? 'beta' : 'stable';
+}
+export function latestRelease(versions, channel) {
+    let best;
+    for (const version of versions) {
+        const parsed = parseReleaseVersion(version);
+        if (!parsed)
+            continue;
+        const isBeta = parsed.beta !== undefined;
+        if (channel === 'beta' ? !isBeta : isBeta)
+            continue;
+        if (!best || compareReleaseVersions(parsed, best.parsed) > 0)
+            best = { version, parsed };
+    }
+    return best?.version;
+}
+export function planSelfUpdate(options) {
+    const distTag = options.channel === 'beta' ? 'beta' : 'latest';
+    const runtimeTarget = options.npmDistTags[distTag];
+    const consoleTarget = latestRelease(options.pypiReleases, options.channel);
+    const runtimeUpdateAvailable = isNewer(runtimeTarget, parseReleaseVersion(options.runtimeVersion));
+    const consoleUpdateAvailable = options.consoleInstalled
+        ? isNewer(consoleTarget, parseReleaseVersion(options.consoleInstalled))
+        : consoleTarget !== undefined;
+    return {
+        channel: options.channel,
+        runtime: { current: options.runtimeVersion, target: runtimeTarget, updateAvailable: runtimeUpdateAvailable },
+        console: { installed: options.consoleInstalled, target: consoleTarget, updateAvailable: consoleUpdateAvailable },
+        ok: !runtimeUpdateAvailable && !consoleUpdateAvailable,
+    };
+}
+function isNewer(target, current) {
+    if (!target || !current)
+        return false;
+    const parsed = parseReleaseVersion(target);
+    return parsed !== null && compareReleaseVersions(parsed, current) > 0;
+}
+export async function fetchNpmDistTags(packageName, fetchImpl = fetch) {
+    const response = await fetchImpl(`https://registry.npmjs.org/${packageName}`);
+    if (!response.ok)
+        throw new Error(`npm registry returned HTTP ${response.status} for ${packageName}.`);
+    const payload = (await response.json());
+    return payload['dist-tags'] ?? {};
+}
+export async function fetchPypiReleases(packageName, fetchImpl = fetch) {
+    const response = await fetchImpl(`https://pypi.org/pypi/${packageName}/json`);
+    if (!response.ok)
+        throw new Error(`PyPI returned HTTP ${response.status} for ${packageName}.`);
+    const payload = (await response.json());
+    return Object.keys(payload.releases ?? {});
+}
+/** Run an update command (npm or uv) with the user's terminal attached. */
+export function runSelfUpdateCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code ?? 1));
+    });
+}
+export function hasCommand(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command, ['--version'], { stdio: 'ignore' });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(code === 0));
+    });
+}
+/** Read `catence-console --version` from PATH; undefined when the Console is not installed. */
+export function readInstalledConsoleVersion() {
+    return new Promise((resolve) => {
+        const child = spawn('catence-console', ['--version'], { stdio: ['ignore', 'pipe', 'inherit'] });
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.once('error', () => resolve(undefined));
+        child.once('close', (code) => {
+            const match = /^catence-console (\S+)/.exec(stdout.trim());
+            resolve(code === 0 && match ? match[1] : undefined);
+        });
+    });
+}
+/** Global npm package root, used to decide whether `catence` can update itself in place. */
+export function npmGlobalPrefix() {
+    return new Promise((resolve) => {
+        const child = spawn('npm', ['prefix', '-g'], { stdio: ['ignore', 'pipe', 'inherit'] });
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.once('error', () => resolve(undefined));
+        child.once('close', (code) => resolve(code === 0 ? stdout.trim() : undefined));
+    });
+}
+export function isGlobalNpmInstall(moduleUrl, npmPrefix) {
+    if (!npmPrefix)
+        return false;
+    return fileURLToPath(moduleUrl).startsWith(`${npmPrefix}/lib/node_modules/`);
+}
+//# sourceMappingURL=self-update.js.map

package/dist/elt/application/management.d.ts

@@ -1,4 +1,5 @@
 import type { CatencePaths } from '../../contracts/runtime.js';
+import { type SyncProgressSnapshot } from '../../contracts/progress.js';
 type SyncProviderChoice = 'intervals' | 'garmin';
 export type ProviderChoice = SyncProviderChoice | 'strava' | 'all';
 export declare function initializeDataStore(paths: CatencePaths): Promise<Record<string, unknown>>;
@@ -21,5 +22,6 @@ export declare function disconnectStravaAccount(paths: CatencePaths): Promise<{
 export declare function linkActivity(paths: CatencePaths, source: string, activity: string): Promise<Record<string, string>>;
 export declare function unlinkActivity(paths: CatencePaths, source: string): Promise<Record<string, string>>;
 export declare function dataStatus(paths: CatencePaths): Promise<Record<string, unknown>>;
+export declare function syncProgress(paths: CatencePaths): Promise<SyncProgressSnapshot>;
 export declare function rebuildRetrievalIndex(paths: CatencePaths): Promise<Record<string, unknown>>;
 export {};

package/dist/elt/application/management.js

@@ -1,25 +1,161 @@
-import { execFile } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import path from 'node:path';
-import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
+import { normalizeProgress, STALE_RUN_TIMEOUT_MS } from '../../contracts/progress.js';
 import { buildRetrievalIndex } from '../../core/retrieval/index.js';
 import { defaultFromDate, ensurePaths, requireIntervalsConfig } from '../../core/runtime/configuration.js';
+import { createSyncLogger } from '../../core/logging.js';
 import { athleteProviderEnvironment } from '../../core/runtime/secrets.js';
 import { importJsonl } from '../ingestion/importer.js';
 import { IntervalsExtractor } from '../ingestion/providers/intervals.js';
 import { completeStravaAuthorization, disconnectStrava, getStravaAuthorizationUrl, syncStravaGear } from '../ingestion/providers/strava/service.js';
 import { setManualActivityLink, unlinkActivitySource } from '../normalization/activities/linking.js';
-import { CatenceDatabase } from '../storage/database.js';
+import { CatenceDatabase, openReadOnlyRepository, ReadOnlyDatabaseError } from '../storage/database.js';
+import { mergeProgress, readRunningProgress, removeProgressSidecar, writeProgressSidecar } from '../storage/progress-sidecar.js';
 import { withDataWriteLock } from '../storage/write-lock.js';
-const execFileAsync = promisify(execFile);
 function packageRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
 }
-async function syncProvider(database, paths, provider, options) {
+function baseProgress(runId, provider, stage) {
+    return {
+        runId, provider, stage, currentStep: null,
+        completedUnits: 0, totalUnits: null, percentComplete: 0, elapsedSeconds: 0,
+        estimatedRemainingSeconds: null, heartbeatAt: new Date().toISOString(),
+    };
+}
+/**
+ * Run the Garmin staging worker with streamed stdout/stderr so progress and
+ * errors surface in real time instead of buffering until the child exits.
+ * Progress NDJSON lines (kind 'progress') are normalized and persisted as
+ * throttled heartbeats; other output is forwarded to the sync logger.
+ */
+function runGarminWorker(runId, arguments_, environment, database, paths, log, onInterruptReady) {
+    return new Promise((resolve) => {
+        const child = spawn('uv', arguments_, { ...environment, stdio: ['ignore', 'pipe', 'pipe'] });
+        let killTimer;
+        onInterruptReady(() => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return;
+                child.kill('SIGKILL');
+            }, 10_000);
+            killTimer.unref();
+        });
+        let lastProgress = null;
+        let lastHeartbeatAt = 0;
+        const heartbeat = (state) => {
+            const now = Date.now();
+            if (now - lastHeartbeatAt < 2_000)
+                return;
+            lastHeartbeatAt = now;
+            void database.heartbeatRun(runId, state).catch((error) => {
+                log.debug('Progress heartbeat failed', { runId, error: error instanceof Error ? error.message : String(error) });
+            });
+            void writeProgressSidecar(paths, runId, state).catch((error) => {
+                log.debug('Progress sidecar write failed', { runId, error: error instanceof Error ? error.message : String(error) });
+            });
+        };
+        const fallback = setInterval(() => {
+            heartbeat(lastProgress ?? baseProgress(runId, 'garmin', 'starting'));
+        }, 30_000);
+        fallback.unref();
+        const buffer = (stream, sink) => {
+            let pending = '';
+            stream.on('data', (chunk) => {
+                pending += chunk.toString('utf8');
+                let newline;
+                while ((newline = pending.indexOf('\n')) >= 0) {
+                    const line = pending.slice(0, newline).trim();
+                    pending = pending.slice(newline + 1);
+                    if (line)
+                        sink(line);
+                }
+            });
+            stream.on('end', () => {
+                const line = pending.trim();
+                if (line)
+                    sink(line);
+            });
+        };
+        buffer(child.stdout, (line) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                log.info(`[garmin] ${line}`);
+                return;
+            }
+            if (typeof parsed === 'object' && parsed !== null && parsed.kind === 'progress') {
+                const state = normalizeProgress(parsed);
+                if (state) {
+                    lastProgress = state;
+                    heartbeat(state);
+                }
+                return;
+            }
+            log.info(`[garmin] ${line}`);
+        });
+        buffer(child.stderr, (line) => log.error(`[garmin] ${line}`));
+        child.on('error', (error) => {
+            clearInterval(fallback);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({ code: 1, signal: null });
+            log.error('Garmin staging worker could not be started', { runId, error: error.message });
+        });
+        child.on('close', (code, signal) => {
+            clearInterval(fallback);
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (code === 0 && lastProgress) {
+                void writeProgressSidecar(paths, runId, { ...lastProgress, stage: 'importing' }).catch(() => undefined);
+            }
+            resolve({ code, signal });
+        });
+    });
+}
+/**
+ * Trap termination signals for the duration of a sync run so an interrupted
+ * run is marked 'interrupted' in sync_runs instead of being left as a zombie
+ * 'running' row. The process exit code mirrors the received signal.
+ */ async function runWithInterruptGuard(runId, database, onInterrupt, state, work) {
+    let exitCode = 0;
+    const handler = (signal) => {
+        if (state.interrupted)
+            return;
+        state.interrupted = true;
+        exitCode = signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 129;
+        void database.markRunInterrupted(runId).catch(() => undefined);
+        try {
+            onInterrupt();
+        }
+        catch {
+            // The child may not exist yet; the run is still marked interrupted.
+        }
+    };
+    process.once('SIGINT', handler);
+    process.once('SIGTERM', handler);
+    process.once('SIGHUP', handler);
+    try {
+        await work();
+    }
+    finally {
+        process.removeListener('SIGINT', handler);
+        process.removeListener('SIGTERM', handler);
+        process.removeListener('SIGHUP', handler);
+        if (state.interrupted)
+            process.exitCode = exitCode;
+    }
+}
+async function syncProvider(database, paths, provider, options, log) {
     const explicitWindow = options.explicitFrom ? { fromDate: options.explicitFrom, toDate: options.toDate, source: 'explicit' } : null;
     const uncoveredExplicitWindow = async (cursorName) => {
         if (!explicitWindow)
@@ -33,6 +169,7 @@ async function syncProvider(database, paths, provider, options) {
     const activityWindow = explicitWindow ? await uncoveredExplicitWindow('activities') : await database.resolveIncrementalWindow(provider, 'activities', options.toDate, defaultFromDate(), 14);
     const hasProviderWork = provider === 'intervals' ? activityWindow !== null : dailyWindow !== null || activityWindow !== null;
     if (!hasProviderWork) {
+        log.debug('No uncovered work; skipping provider', { provider, daily: dailyWindow ?? null, activities: activityWindow ?? null });
         return {
             runId: null, provider, fromDate: null,
             dailyFromDate: dailyWindow?.fromDate ?? null, dailyToDate: dailyWindow?.toDate ?? null,
@@ -43,13 +180,22 @@ async function syncProvider(database, paths, provider, options) {
     }
     const fromDate = [dailyWindow?.fromDate, activityWindow?.fromDate].filter((date) => Boolean(date)).sort()[0];
     const runId = await database.beginRun(provider, fromDate);
+    log.info('Starting sync run', {
+        runId, provider, fromDate, toDate: options.toDate,
+        dailyFrom: dailyWindow?.fromDate ?? null, dailyTo: dailyWindow?.toDate ?? null,
+        activityFrom: activityWindow?.fromDate ?? null, activityTo: activityWindow?.toDate ?? null,
+        backfill: options.backfill, refreshActivities: options.refreshActivities,
+    });
     let extractionStarted = false;
+    const guard = { interrupted: false };
     try {
         if (provider === 'intervals') {
             const environment = await athleteProviderEnvironment(paths);
             const config = requireIntervalsConfig(environment);
             extractionStarted = true;
-            await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
+            await runWithInterruptGuard(runId, database, () => undefined, guard, async () => {
+                await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId, log).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
+            });
         }
         else {
             const output = path.join(paths.staging, 'garmin', `${runId}.jsonl`);
@@ -71,22 +217,44 @@ async function syncProvider(database, paths, provider, options) {
                 arguments_.push('--skip-activities');
             if (options.backfill && !options.refreshActivities)
                 arguments_.push('--historical-only');
-            await execFileAsync('uv', arguments_, {
-                cwd: packageRoot(),
-                env: { ...(await athleteProviderEnvironment(paths)), UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+            let interruptChild = null;
+            await runWithInterruptGuard(runId, database, () => interruptChild?.(), guard, async () => {
+                const outcome = await runGarminWorker(runId, arguments_, {
+                    cwd: packageRoot(),
+                    env: { ...(await athleteProviderEnvironment(paths)), UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+                }, database, paths, log, (kill) => { interruptChild = kill; });
+                if (!guard.interrupted && outcome.code !== 0) {
+                    throw new Error(`Garmin staging worker exited with code ${outcome.code}${outcome.signal ? ` (${outcome.signal})` : ''}.`);
+                }
             });
-            if (!existsSync(output))
-                throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
-            await importJsonl(database, runId, output);
+            if (!guard.interrupted) {
+                if (!existsSync(output))
+                    throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
+                await importJsonl(database, runId, output, log);
+            }
         }
     }
     catch (error) {
-        await database.addError(runId, provider, 'sync', null, error instanceof Error ? error.message : String(error), true);
+        if (!guard.interrupted) {
+            const message = error instanceof Error ? error.message : String(error);
+            log.error('Sync run failed', { runId, provider, error: message, stack: error instanceof Error ? error.stack : undefined });
+            await database.addError(runId, provider, 'sync', null, message, true);
+            await database.heartbeatRun(runId, baseProgress(runId, provider, 'failed')).catch(() => undefined);
+        }
     }
     finally {
-        await database.finishRun(runId);
+        if (guard.interrupted) {
+            await database.markRunInterrupted(runId);
+            log.warn('Sync run interrupted', { runId, provider });
+        }
+        else {
+            await database.finishRun(runId);
+        }
+        await removeProgressSidecar(paths, runId).catch(() => undefined);
+        const [run] = await database.rows('SELECT status, error_count FROM sync_runs WHERE run_id = $runId', { runId });
+        log.info('Sync run finished', { runId, provider, status: run?.status ?? 'unknown', errorCount: run?.error_count ?? 0 });
     }
-    if (options.advanceCursor && !options.explicitFrom && extractionStarted) {
+    if (!guard.interrupted && options.advanceCursor && !options.explicitFrom && extractionStarted) {
         await database.advanceIncrementalCursor(provider, 'daily', runId, options.toDate, 3);
         await database.advanceIncrementalCursor(provider, 'activities', runId, options.toDate, 14);
     }
@@ -109,13 +277,21 @@ export async function syncData(paths, provider, explicitFrom, advanceCursor = tr
     if (provider === 'strava')
         return { provider, result: await syncStravaGear(paths) };
     const database = await CatenceDatabase.open(paths);
+    const log = createSyncLogger(paths);
     try {
+        const timedOutRuns = await database.interruptStaleSyncRuns(STALE_RUN_TIMEOUT_MS);
+        if (timedOutRuns.runIds.length > 0) {
+            log.warn('Marked stale sync runs as timed out', { runIds: timedOutRuns.runIds, timeoutMs: STALE_RUN_TIMEOUT_MS });
+        }
+        for (const runId of timedOutRuns.runIds) {
+            await removeProgressSidecar(paths, runId).catch(() => undefined);
+        }
         const providers = provider === 'all' ? ['intervals', 'garmin'] : [provider];
         const toDate = new Date().toISOString().slice(0, 10);
         const runs = [];
         for (const source of providers)
-            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }));
-        return { runIds: runs.flatMap((run) => run.runId ? [run.runId] : []), runs };
+            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }, log));
+        return { runIds: runs.flatMap((run) => run.runId ? [run.runId] : []), runs, timedOutRuns: timedOutRuns.runIds };
     }
     finally {
         await database.close();
@@ -125,12 +301,14 @@ export async function retryDataSync(paths, previousRunId) {
     await ensurePaths(paths);
     const database = await CatenceDatabase.open(paths);
     try {
+        await database.interruptStaleSyncRuns(STALE_RUN_TIMEOUT_MS);
         const previous = await database.getRun(previousRunId);
         if (!previous)
             throw new Error(`No sync run found for ${previousRunId}.`);
         if (previous.provider === 'strava')
             throw new Error('Retry Strava gear sync with `catence-data sync --provider strava`.');
-        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false });
+        const log = createSyncLogger(paths);
+        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false }, log);
         return { retriedRun: previousRunId, runId: run.runId, run };
     }
     finally {
@@ -271,6 +449,30 @@ export async function dataStatus(paths) {
         await database.close();
     }
 }
+export async function syncProgress(paths) {
+    await ensurePaths(paths);
+    // Live progress must stay readable while a sync run holds the single-writer
+    // DuckDB lock, so the running set comes from sidecar heartbeat files first.
+    const sidecars = await readRunningProgress(paths);
+    let dbRunning = [];
+    let dbRecent = [];
+    try {
+        const repository = await openReadOnlyRepository(paths);
+        try {
+            const snapshot = await repository.progress();
+            dbRunning = snapshot.running;
+            dbRecent = snapshot.recent;
+        }
+        finally {
+            await repository.close();
+        }
+    }
+    catch (error) {
+        if (!(error instanceof ReadOnlyDatabaseError))
+            throw error;
+    }
+    return mergeProgress(dbRunning, dbRecent, sidecars);
+}
 export async function rebuildRetrievalIndex(paths) {
     if (!existsSync(paths.database))
         throw new Error('No Catence database exists yet. Complete a sync before building the retrieval index.');

package/dist/elt/ingestion/importer.d.ts

@@ -1,7 +1,8 @@
 import type { CatenceDatabase } from '../storage/database.js';
 import { type StagingRecord } from '../../contracts/staging.js';
-export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord): Promise<void>;
-export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
+import type { SyncLogger } from '../../core/logging.js';
+export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord, log?: SyncLogger): Promise<void>;
+export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string, log?: SyncLogger): Promise<number>;
 export declare function importSingleStagingFile(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
 export declare function queueWorkItem(database: CatenceDatabase, runId: string, provider: 'intervals' | 'garmin' | 'strava', endpoint: string, remoteId: string | null, scope: unknown): Promise<string>;
 export declare function completeWorkItem(database: CatenceDatabase, itemId: string): Promise<void>;

package/dist/elt/ingestion/importer.js

@@ -7,7 +7,7 @@ import { importSourceEntity, refreshActivityQuality } from '../normalization/nor
 import { normalizeStravaEntity } from '../normalization/segments/strava-normalizer.js';
 import { reconcileActivityLink } from '../normalization/activities/linking.js';
 import { json } from '../storage/sql.js';
-export async function importRecord(database, runId, record) {
+export async function importRecord(database, runId, record, log) {
     if (record.kind === 'run_manifest') {
         if (record.runId !== runId)
             throw new Error(`Staging manifest run ${record.runId} does not match importer run ${runId}.`);
@@ -54,8 +54,9 @@ export async function importRecord(database, runId, record) {
         return;
     }
     await database.addError(runId, record.provider, record.endpoint, record.remoteId, record.message, record.retryable);
+    log?.warn('Staging record reported an extraction error', { runId, provider: record.provider, endpoint: record.endpoint, remoteId: record.remoteId, error: record.message });
 }
-export async function importJsonl(database, runId, filePath) {
+export async function importJsonl(database, runId, filePath, log) {
     let count = 0;
     const file = createReadStream(filePath, { encoding: 'utf8' });
     const lines = createInterface({ input: file, crlfDelay: Infinity });
@@ -63,7 +64,7 @@ export async function importJsonl(database, runId, filePath) {
         if (!line.trim())
             continue;
         const record = stagingRecordSchema.parse(JSON.parse(line));
-        await importRecord(database, runId, record);
+        await importRecord(database, runId, record, log);
         count += 1;
     }
     return count;

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

@@ -1,12 +1,14 @@
 import type { CatenceDatabase } from '../../storage/database.js';
 import type { CatencePaths } from '../../../contracts/runtime.js';
+import type { SyncLogger } from '../../../core/logging.js';
 export declare class IntervalsExtractor {
     private readonly database;
     private readonly paths;
     private readonly apiKey;
     private readonly athleteId;
+    private readonly log;
     private readonly client;
-    constructor(database: CatenceDatabase, paths: CatencePaths, apiKey: string, athleteId: string);
+    constructor(database: CatenceDatabase, paths: CatencePaths, apiKey: string, athleteId: string, log: SyncLogger);
     sync(runId: string, activityWindow: {
         fromDate: string;
         toDate: string;

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

@@ -42,12 +42,14 @@ export class IntervalsExtractor {
     paths;
     apiKey;
     athleteId;
+    log;
     client;
-    constructor(database, paths, apiKey, athleteId) {
+    constructor(database, paths, apiKey, athleteId, log) {
         this.database = database;
         this.paths = paths;
         this.apiKey = apiKey;
         this.athleteId = athleteId;
+        this.log = log;
         // The typed client is used for provider-compatible authentication and the
         // primary identity request. Manifest-only calls below intentionally use
         // the same read-only credentials to cover endpoint families not wrapped by it.
@@ -189,6 +191,7 @@ export class IntervalsExtractor {
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             await failWorkItem(this.database, workId, message);
+            this.log.warn('Endpoint capture failed', { runId, provider: 'intervals', endpoint, remoteId, error: message });
             await this.database.addError(runId, 'intervals', endpoint, remoteId, message, true);
             return undefined;
         }

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

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

package/dist/elt/storage/database.d.ts

@@ -2,6 +2,7 @@ import { ReadOnlyRepository } from '../../core/query/repository.js';
 import type { CatencePaths } from '../../contracts/runtime.js';
 import type { QueryBindings, WriteDataStore } from '../../contracts/storage.js';
 import type { Provider } from '../../contracts/staging.js';
+import { type InterruptedRuns, type SyncProgressSnapshot, type SyncProgressState } from '../../contracts/progress.js';
 export declare class CatenceDatabase implements WriteDataStore {
     private readonly instance;
     private readonly connection;
@@ -16,6 +17,10 @@ export declare class CatenceDatabase implements WriteDataStore {
     interrupt(): void;
     beginRun(provider: Provider, fromDate: string, runId?: `${string}-${string}-${string}-${string}-${string}`): Promise<string>;
     finishRun(runId: string): Promise<void>;
+    heartbeatRun(runId: string, progress: SyncProgressState): Promise<void>;
+    markRunInterrupted(runId: string, stage?: string): Promise<void>;
+    interruptStaleSyncRuns(timeoutMs?: number): Promise<InterruptedRuns>;
+    syncProgress(): Promise<SyncProgressSnapshot>;
     addError(runId: string, provider: Provider, endpoint: string, remoteId: string | null, message: string, retryable: boolean): Promise<void>;
     status(): Promise<Record<string, unknown>>;
     getRun(runId: string): Promise<{
@@ -66,9 +71,9 @@ export declare class ReadOnlyCatenceDatabase {
     interrupt(): void;
     private withConnection;
 }
-/** Compose core read services with the DuckDB-backed, read-only adapter. */
-export declare function openReadOnlyRepository(paths: CatencePaths): Promise<ReadOnlyRepository>;
 export declare class ReadOnlyDatabaseError extends Error {
     readonly code: 'data_sync_in_progress' | 'data_unavailable';
     constructor(code: 'data_sync_in_progress' | 'data_unavailable', message: string);
 }
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export declare function openReadOnlyRepository(paths: CatencePaths): Promise<ReadOnlyRepository>;