catence 0.0.0 → 0.1.0

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

@@ -0,0 +1,365 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { ensurePaths, loadCatenceConfig } from '../../../../core/runtime/configuration.js';
+import { CatenceDatabase, openReadOnlyRepository } from '../../../storage/database.js';
+import { importJsonl } from '../../importer.js';
+import { withDataWriteLock } from '../../../storage/write-lock.js';
+const execFileAsync = promisify(execFile);
+export class StravaRateLimitError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'StravaRateLimitError';
+    }
+}
+export class StravaEnrichmentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StravaEnrichmentError';
+    }
+}
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+}
+function toFiniteInteger(value) {
+    if (!value)
+        return null;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+function parsePair(value) {
+    if (!value)
+        return [null, null];
+    const [first, second] = value.split(',').map((part) => toFiniteInteger(part.trim()));
+    return [first ?? null, second ?? null];
+}
+async function readWorkerResult(filePath) {
+    if (!existsSync(filePath))
+        throw new StravaEnrichmentError('Strava worker did not write its result manifest.');
+    const parsed = JSON.parse(await readFile(filePath, 'utf8'));
+    if (!parsed || typeof parsed.status !== 'string')
+        throw new StravaEnrichmentError('Strava worker wrote an invalid result manifest.');
+    return parsed;
+}
+async function invokeWorker(paths, args, resultPath) {
+    try {
+        await execFileAsync('uv', ['run', 'python', '-m', 'python.catence.providers.strava.cli', ...args, '--data-dir', paths.root, '--result', resultPath], {
+            cwd: packageRoot(),
+            env: { ...process.env, UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+        });
+    }
+    catch (error) {
+        if (!existsSync(resultPath)) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new StravaEnrichmentError(`Strava worker failed before it could report a result: ${message}`);
+        }
+    }
+    return readWorkerResult(resultPath);
+}
+async function storeRateState(database, result) {
+    const headers = result.rateHeaders ?? {};
+    const [limit15, limitDay] = parsePair(headers['x-ratelimit-limit']);
+    const [usage15, usageDay] = parsePair(headers['x-ratelimit-usage']);
+    const isThrottled = result.status === 'partial' && /rate limit|429/i.test(result.message ?? '');
+    await database.run(`INSERT INTO strava_rate_state (account_id, read_limit_15m, read_usage_15m, read_limit_day, read_usage_day, blocked_until, observed_at)
+     VALUES ('authenticated_athlete', $limit15, $usage15, $limitDay, $usageDay, CASE WHEN $throttled THEN now() + INTERVAL 15 MINUTE ELSE NULL END, now())
+     ON CONFLICT (account_id) DO UPDATE SET
+       read_limit_15m = COALESCE(excluded.read_limit_15m, strava_rate_state.read_limit_15m),
+       read_usage_15m = COALESCE(excluded.read_usage_15m, strava_rate_state.read_usage_15m),
+       read_limit_day = COALESCE(excluded.read_limit_day, strava_rate_state.read_limit_day),
+       read_usage_day = COALESCE(excluded.read_usage_day, strava_rate_state.read_usage_day),
+       blocked_until = CASE WHEN excluded.blocked_until IS NOT NULL THEN excluded.blocked_until ELSE strava_rate_state.blocked_until END,
+       observed_at = now()`, { limit15, usage15, limitDay, usageDay, throttled: isThrottled });
+}
+async function checkBudget(database, paths) {
+    const config = await loadCatenceConfig(paths);
+    const budget = config.providers?.strava?.budget;
+    const rate = (await database.rows(`SELECT blocked_until, read_usage_15m, read_usage_day FROM strava_rate_state WHERE account_id = 'authenticated_athlete'`))[0];
+    const blockedUntil = rate?.blocked_until ? new Date(rate.blocked_until).getTime() : 0;
+    if (blockedUntil > Date.now())
+        throw new StravaRateLimitError('Strava has recently throttled Catence; retry after its remote rate-limit window.', Math.ceil((blockedUntil - Date.now()) / 1_000));
+    if (budget?.readRequestsPer15Minutes && (rate?.read_usage_15m ?? 0) >= budget.readRequestsPer15Minutes)
+        throw new StravaRateLimitError('Catence local Strava 15-minute request budget has been reached.');
+    if (budget?.readRequestsPerDay && (rate?.read_usage_day ?? 0) >= budget.readRequestsPerDay)
+        throw new StravaRateLimitError('Catence local Strava daily request budget has been reached.');
+}
+async function writeState(database, resourceType, remoteId, result) {
+    const status = result.status === 'completed' ? 'completed' : result.status;
+    await database.run(`INSERT INTO strava_enrichment_state (resource_type, remote_id, status, fetched_at, completed_at, continuation_page, detail_json)
+     VALUES ($resourceType, $remoteId, $status, now(), CASE WHEN $status = 'completed' THEN now() ELSE NULL END, $continuationPage, $detail)
+     ON CONFLICT (resource_type, remote_id) DO UPDATE SET
+       status = excluded.status, fetched_at = now(), completed_at = CASE WHEN excluded.status = 'completed' THEN now() ELSE strava_enrichment_state.completed_at END,
+       continuation_page = excluded.continuation_page, detail_json = excluded.detail_json`, { resourceType, remoteId, status, continuationPage: result.continuationPage ?? null, detail: JSON.stringify(result) });
+}
+async function cachedState(database, resourceType, remoteId) {
+    const state = await database.rows(`SELECT status, detail_json, fetched_at, completed_at FROM strava_enrichment_state WHERE resource_type = $resourceType AND remote_id = $remoteId`, { resourceType, remoteId });
+    const row = state[0];
+    if (!row || row.status !== 'completed')
+        return null;
+    const detail = typeof row.detail_json === 'string' ? JSON.parse(row.detail_json) : row.detail_json;
+    return { ...detail, cache: { reused: true, fetchedAt: row.fetched_at, completedAt: row.completed_at } };
+}
+async function runReadOperation(paths, operation, extraArgs, resource, refresh = false) {
+    return withDataWriteLock(paths, async () => {
+        await ensurePaths(paths);
+        const database = await CatenceDatabase.open(paths);
+        try {
+            if (!refresh) {
+                const cached = await cachedState(database, resource.type, resource.id);
+                if (cached)
+                    return cached;
+            }
+            await checkBudget(database, paths);
+            const runId = await database.beginRun('strava', new Date().toISOString().slice(0, 10));
+            const directory = path.join(paths.staging, 'strava');
+            const stagingPath = path.join(directory, `${runId}.jsonl`);
+            const resultPath = path.join(directory, `${runId}.result.json`);
+            let result;
+            try {
+                result = await invokeWorker(paths, ['--mode', operation, '--run-id', runId, '--output', stagingPath, ...extraArgs], resultPath);
+                if (existsSync(stagingPath))
+                    await importJsonl(database, runId, stagingPath);
+                await storeRateState(database, result);
+                await writeState(database, resource.type, resource.id, result);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                await database.addError(runId, 'strava', operation, resource.id, message, true);
+                throw error;
+            }
+            finally {
+                await database.finishRun(runId);
+            }
+            if (result.status === 'error')
+                throw new StravaEnrichmentError(result.message ?? 'Strava did not complete the requested enrichment.');
+            return result;
+        }
+        finally {
+            await database.close();
+        }
+    });
+}
+export async function syncStravaGear(paths, refresh = true) {
+    return runReadOperation(paths, 'gear', [], { type: 'gear', id: 'authenticated_athlete' }, refresh);
+}
+/** Returns a Strava activity ID only for formats that identify one directly. */
+export function stravaActivityIdFromExternalId(value) {
+    const externalId = value?.trim();
+    if (!externalId)
+        return null;
+    const match = externalId.match(/^strava:(\d+)$/i)
+        ?? externalId.match(/^https?:\/\/(?:www\.)?strava\.com\/activities\/(\d+)\/?$/i);
+    return match?.[1] ?? null;
+}
+function object(value) {
+    if (value && typeof value === 'object')
+        return value;
+    if (typeof value !== 'string')
+        return {};
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function stravaActivityIdFromSourcePayload(value) {
+    const stravaId = object(value).strava_id;
+    const candidate = typeof stravaId === 'number' ? String(stravaId) : typeof stravaId === 'string' ? stravaId.trim() : '';
+    return /^\d+$/.test(candidate) ? candidate : null;
+}
+/** Prefer a persisted Strava source over a generic provider external ID. */
+export function resolveStravaActivityId(activityId, matches) {
+    return stravaActivityIdFromExternalId(activityId)
+        ?? matches.find((match) => match.provider === 'strava')?.remote_activity_id
+        ?? null;
+}
+export async function multisportChildActivitySourceIds(paths, activityId) {
+    const repository = await openReadOnlyRepository(paths);
+    try {
+        const parent = (await repository.rows(`
+      SELECT coalesce(
+        try_cast(json_extract_string(raw.payload_json, '$.isMultiSportParent') AS BOOLEAN),
+        try_cast(json_extract_string(raw.payload_json, '$.isParent') AS BOOLEAN),
+        false
+      ) AS is_multisport_parent
+      FROM activity_sources AS source
+      JOIN source_entities AS raw ON raw.provider = source.provider AND raw.entity_type = 'activity' AND raw.remote_id = source.remote_activity_id
+      WHERE source.activity_source_id = $activityId AND source.provider = 'garmin'
+    `, { activityId }))[0];
+        if (!parent?.is_multisport_parent)
+            return null;
+        const children = await repository.rows(`
+      SELECT child_source.activity_source_id
+      FROM activity_sources AS parent_source
+      JOIN source_entities AS child_raw
+        ON child_raw.provider = 'garmin' AND child_raw.entity_type = 'activity' AND child_raw.parent_remote_id = parent_source.remote_activity_id
+      JOIN activity_sources AS child_source
+        ON child_source.provider = 'garmin' AND child_source.remote_activity_id = child_raw.remote_id
+      JOIN activities AS child_activity ON child_activity.activity_id = child_source.activity_id
+      WHERE parent_source.activity_source_id = $activityId
+        AND parent_source.provider = 'garmin'
+        AND lower(coalesce(child_activity.sport, '')) NOT LIKE '%transition%'
+      ORDER BY child_activity.started_at_utc, child_source.activity_source_id
+    `, { activityId });
+        return children.map((child) => child.activity_source_id);
+    }
+    finally {
+        await repository.close();
+    }
+}
+export async function hydrateStravaActivity(paths, activityId, refresh = false) {
+    const multisportChildren = await multisportChildActivitySourceIds(paths, activityId);
+    if (multisportChildren) {
+        if (!multisportChildren.length) {
+            throw new StravaEnrichmentError('This Garmin multisport parent has no staged child activities. Refresh the Garmin activity before hydrating Strava.');
+        }
+        const childOutcomes = [];
+        for (const childActivityId of multisportChildren) {
+            const result = await hydrateStravaActivity(paths, childActivityId, refresh);
+            const status = typeof result.status === 'string' ? result.status : 'completed';
+            childOutcomes.push({ activityId: childActivityId, status, result });
+        }
+        return {
+            status: childOutcomes.every((outcome) => outcome.status === 'completed') ? 'completed' : 'partial',
+            hydrationStrategy: 'garmin_multisport_children',
+            childOutcomes,
+        };
+    }
+    return withDataWriteLock(paths, async () => {
+        await ensurePaths(paths);
+        const database = await CatenceDatabase.open(paths);
+        try {
+            const matches = await database.rows(`
+        SELECT source.activity_source_id, source.activity_id, source.provider, source.remote_activity_id, source.external_id, raw.payload_json AS source_payload, activity.started_at_utc, activity.sport, summary.distance_m, summary.elapsed_s
+        FROM activity_sources source JOIN activities activity USING (activity_id)
+        LEFT JOIN activity_summaries summary USING (activity_source_id)
+        LEFT JOIN source_entities raw ON raw.provider = source.provider AND raw.entity_type = 'activity' AND raw.remote_id = source.remote_activity_id
+        LEFT JOIN activity_links link USING (activity_source_id)
+        WHERE source.activity_source_id = $activityId
+          OR source.activity_id = (SELECT activity_id FROM activity_sources WHERE activity_source_id = $activityId)
+          OR link.activity_id = (SELECT activity_id FROM activity_sources WHERE activity_source_id = $activityId)
+        ORDER BY CASE source.provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END
+      `, { activityId });
+            const activity = matches[0];
+            if (!activity)
+                throw new StravaEnrichmentError(`No Catence activity or activity source named ${activityId} exists.`);
+            const requestedSource = matches.find((match) => match.activity_source_id === activityId);
+            const sourceStravaActivityId = requestedSource ? stravaActivityIdFromSourcePayload(requestedSource.source_payload) : null;
+            const directStravaActivityId = sourceStravaActivityId ?? resolveStravaActivityId(activityId, matches);
+            const matchMethod = sourceStravaActivityId ? 'source_strava_id' : directStravaActivityId ? 'linked_strava_source' : null;
+            const resource = { type: 'activity', id: activity.activity_source_id };
+            if (!refresh) {
+                const cached = await cachedState(database, resource.type, resource.id);
+                if (cached)
+                    return cached;
+            }
+            if (!directStravaActivityId && (!activity.started_at_utc || !activity.sport || activity.distance_m === null || activity.elapsed_s === null)) {
+                throw new StravaEnrichmentError('This activity lacks the timestamp, sport, distance, or elapsed duration required for safe Strava matching.');
+            }
+            await checkBudget(database, paths);
+            const runId = await database.beginRun('strava', new Date().toISOString().slice(0, 10));
+            const directory = path.join(paths.staging, 'strava');
+            const stagingPath = path.join(directory, `${runId}.jsonl`);
+            const resultPath = path.join(directory, `${runId}.result.json`);
+            let result;
+            try {
+                const matchingArguments = [
+                    ...(directStravaActivityId ? ['--strava-activity-id', directStravaActivityId] : []),
+                    ...(matchMethod ? ['--strava-match-method', matchMethod] : []),
+                    ...(activity.started_at_utc && activity.sport && activity.distance_m !== null && activity.elapsed_s !== null
+                        ? ['--started-at', new Date(activity.started_at_utc).toISOString(), '--sport', activity.sport, '--distance-m', String(activity.distance_m), '--elapsed-s', String(activity.elapsed_s)]
+                        : []),
+                ];
+                result = await invokeWorker(paths, [
+                    '--mode', 'activity', '--run-id', runId, '--output', stagingPath,
+                    '--activity-id', activity.activity_source_id, ...matchingArguments,
+                    ...(refresh ? ['--refresh'] : []),
+                ], resultPath);
+                if (existsSync(stagingPath))
+                    await importJsonl(database, runId, stagingPath);
+                await storeRateState(database, result);
+                await writeState(database, resource.type, resource.id, result);
+            }
+            catch (error) {
+                await database.addError(runId, 'strava', 'activity', activity.activity_source_id, error instanceof Error ? error.message : String(error), true);
+                throw error;
+            }
+            finally {
+                await database.finishRun(runId);
+            }
+            if (result.status === 'error')
+                throw new StravaEnrichmentError(result.message ?? 'Strava activity hydration failed.');
+            return result;
+        }
+        finally {
+            await database.close();
+        }
+    });
+}
+export async function hydrateStravaSegmentHistory(paths, segmentId, refresh = false) {
+    return withDataWriteLock(paths, async () => {
+        await ensurePaths(paths);
+        const database = await CatenceDatabase.open(paths);
+        try {
+            const found = await database.rows('SELECT segment_id FROM strava_segments WHERE segment_id = $segmentId', { segmentId });
+            if (!found[0])
+                throw new StravaEnrichmentError(`Strava segment ${segmentId} is not persisted. Hydrate an activity containing it first.`);
+            const resource = { type: 'segment_history', id: segmentId };
+            if (!refresh) {
+                const cached = await cachedState(database, resource.type, resource.id);
+                if (cached)
+                    return cached;
+            }
+            const continuation = (await database.rows('SELECT continuation_page FROM strava_enrichment_state WHERE resource_type = $type AND remote_id = $segmentId', { type: resource.type, segmentId }))[0]?.continuation_page;
+            await checkBudget(database, paths);
+            const runId = await database.beginRun('strava', new Date().toISOString().slice(0, 10));
+            const directory = path.join(paths.staging, 'strava');
+            const stagingPath = path.join(directory, `${runId}.jsonl`);
+            const resultPath = path.join(directory, `${runId}.result.json`);
+            let result;
+            try {
+                result = await invokeWorker(paths, ['--mode', 'segment-history', '--run-id', runId, '--output', stagingPath, '--segment-id', segmentId, '--start-page', String(continuation ?? 1), ...(refresh ? ['--refresh'] : [])], resultPath);
+                if (existsSync(stagingPath))
+                    await importJsonl(database, runId, stagingPath);
+                await storeRateState(database, result);
+                await writeState(database, resource.type, resource.id, result);
+            }
+            catch (error) {
+                await database.addError(runId, 'strava', 'segment-history', segmentId, error instanceof Error ? error.message : String(error), true);
+                throw error;
+            }
+            finally {
+                await database.finishRun(runId);
+            }
+            if (result.status === 'error')
+                throw new StravaEnrichmentError(result.message ?? 'Strava segment history hydration failed.');
+            return result;
+        }
+        finally {
+            await database.close();
+        }
+    });
+}
+export async function getStravaAuthorizationUrl(paths, redirectUri) {
+    await ensurePaths(paths);
+    const resultPath = path.join(paths.staging, 'strava', `authorization-${Date.now()}.json`);
+    return invokeWorker(paths, ['--mode', 'authorization-url', '--redirect-uri', redirectUri], resultPath);
+}
+export async function completeStravaAuthorization(paths, code, redirectUri) {
+    await ensurePaths(paths);
+    const resultPath = path.join(paths.staging, 'strava', `authorization-${Date.now()}.json`);
+    return invokeWorker(paths, ['--mode', 'auth', '--code', code, '--redirect-uri', redirectUri], resultPath);
+}
+export async function disconnectStrava(paths) {
+    await withDataWriteLock(paths, async () => {
+        await rm(path.join(paths.secrets, 'strava.json'), { force: true });
+    });
+}
+//# sourceMappingURL=service.js.map

package/dist/elt/normalization/activities/linking.d.ts

@@ -0,0 +1,5 @@
+import type { CatenceDatabase } from '../../storage/database.js';
+/** Attach a source to a logical activity only when its link is provable or uniquely high-confidence. */
+export declare function reconcileActivityLink(database: CatenceDatabase, activitySourceId: string): Promise<void>;
+export declare function setManualActivityLink(database: CatenceDatabase, activitySourceId: string, activityId: string): Promise<void>;
+export declare function unlinkActivitySource(database: CatenceDatabase, activitySourceId: string): Promise<void>;

package/dist/elt/normalization/activities/linking.js

@@ -0,0 +1,165 @@
+import { json } from '../../storage/sql.js';
+function sportFamily(value) {
+    if (!value)
+        return null;
+    const normalized = value.toLowerCase().replaceAll(/[^a-z]/g, '');
+    if (normalized.includes('ride') || normalized.includes('cycling') || normalized.includes('bik'))
+        return 'ride';
+    if (normalized.includes('run'))
+        return 'run';
+    if (normalized.includes('swim'))
+        return 'swim';
+    return normalized || null;
+}
+function isVirtualOrIndoor(value) {
+    return Boolean(value && /virtual|indoor/i.test(value));
+}
+function timestamp(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value instanceof Date ? value.toISOString() : value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function qualifies(source, candidate) {
+    if (source.provider === candidate.provider || !source.started_at_utc || !candidate.started_at_utc)
+        return null;
+    if (!source.distance_m || !candidate.distance_m || !source.moving_s || !candidate.moving_s)
+        return null;
+    if (sportFamily(source.sport) !== sportFamily(candidate.sport))
+        return null;
+    if (isVirtualOrIndoor(source.sport) !== isVirtualOrIndoor(candidate.sport))
+        return null;
+    const startDelta = Math.abs(timestamp(source.started_at_utc) - timestamp(candidate.started_at_utc)) / 1_000;
+    const durationDelta = Math.abs(source.moving_s - candidate.moving_s);
+    const distanceDelta = Math.abs(source.distance_m - candidate.distance_m);
+    const maxDuration = Math.max(120, source.moving_s * 0.05);
+    const maxDistance = Math.max(200, source.distance_m * 0.025);
+    if (startDelta > 90 || durationDelta > maxDuration || distanceDelta > maxDistance)
+        return null;
+    const score = 1 - ((startDelta / 90) + (durationDelta / maxDuration) + (distanceDelta / maxDistance)) / 3;
+    return { score, evidence: { sportFamily: sportFamily(source.sport), startDeltaSeconds: startDelta, durationDeltaSeconds: durationDelta, distanceDeltaMeters: distanceDelta, thresholds: { startSeconds: 90, durationSeconds: maxDuration, distanceMeters: maxDistance } } };
+}
+/** Attach a source to a logical activity only when its link is provable or uniquely high-confidence. */
+export async function reconcileActivityLink(database, activitySourceId) {
+    const sources = await database.rows(`
+    SELECT source.activity_source_id, source.activity_id, source.provider, source.remote_activity_id, source.external_id,
+      activity.started_at_utc, activity.sport, summary.distance_m, summary.moving_s
+    FROM activity_sources source
+    JOIN activities activity USING (activity_id)
+    LEFT JOIN activity_summaries summary USING (activity_source_id)
+    WHERE source.activity_source_id = $activitySourceId
+  `, { activitySourceId });
+    const source = sources[0];
+    if (!source)
+        return;
+    const current = await database.rows('SELECT method, activity_id FROM activity_links WHERE activity_source_id = $activitySourceId', { activitySourceId });
+    if (current[0]?.method === 'manual' || current[0]?.method === 'fuzzy_high_confidence') {
+        if (source.activity_id !== current[0].activity_id) {
+            await database.run('UPDATE activity_sources SET activity_id = $activityId WHERE activity_source_id = $activitySourceId', { activityId: current[0].activity_id, activitySourceId });
+        }
+        return;
+    }
+    const externalCandidates = source.provider === 'intervals' && source.external_id
+        ? await database.rows(`
+      SELECT source.activity_source_id, source.activity_id, source.provider, source.remote_activity_id, source.external_id,
+        activity.started_at_utc, activity.sport, summary.distance_m, summary.moving_s
+      FROM activity_sources source
+      JOIN activities activity USING (activity_id)
+      LEFT JOIN activity_summaries summary USING (activity_source_id)
+      WHERE source.provider = 'garmin' AND source.remote_activity_id = $externalId
+    `, { externalId: source.external_id })
+        : source.provider === 'garmin'
+            ? await database.rows(`
+        SELECT source.activity_source_id, source.activity_id, source.provider, source.remote_activity_id, source.external_id,
+          activity.started_at_utc, activity.sport, summary.distance_m, summary.moving_s
+        FROM activity_sources source
+        JOIN activities activity USING (activity_id)
+        LEFT JOIN activity_summaries summary USING (activity_source_id)
+        WHERE source.provider = 'intervals' AND source.external_id = $remoteActivityId
+      `, { remoteActivityId: source.remote_activity_id })
+            : [];
+    const externalCandidate = externalCandidates.length === 1 ? externalCandidates[0] : null;
+    if (externalCandidate) {
+        const linkMethods = await database.rows(`SELECT activity_source_id, method FROM activity_links WHERE activity_source_id = $sourceId OR activity_source_id = $candidateId`, { sourceId: source.activity_source_id, candidateId: externalCandidate.activity_source_id });
+        if (!linkMethods.some((link) => link.method === 'manual')) {
+            const garmin = source.provider === 'garmin' ? source : externalCandidate;
+            const intervals = source.provider === 'intervals' ? source : externalCandidate;
+            const targetActivityId = garmin.activity_id;
+            const previousActivityIds = new Set([source.activity_id, externalCandidate.activity_id]);
+            for (const linkedSource of [source, externalCandidate]) {
+                await database.run('UPDATE activity_sources SET activity_id = $activityId WHERE activity_source_id = $activitySourceId', {
+                    activityId: targetActivityId, activitySourceId: linkedSource.activity_source_id,
+                });
+                await database.run(`INSERT INTO activity_links VALUES ($activitySourceId, $activityId, 'strong_external_id', 1.0, $evidence, now())
+           ON CONFLICT (activity_source_id) DO UPDATE SET activity_id = excluded.activity_id, method = excluded.method,
+             confidence = excluded.confidence, evidence_json = excluded.evidence_json, linked_at = now()`, {
+                    activitySourceId: linkedSource.activity_source_id, activityId: targetActivityId,
+                    evidence: json({ matchedActivitySourceId: linkedSource.provider === 'garmin' ? intervals.activity_source_id : garmin.activity_source_id, externalId: intervals.external_id }),
+                });
+            }
+            await database.run(`UPDATE activities SET link_state = 'strong_external_id' WHERE activity_id = $activityId`, { activityId: targetActivityId });
+            for (const previousActivityId of previousActivityIds) {
+                await database.run('DELETE FROM activities WHERE activity_id = $activityId AND NOT EXISTS (SELECT 1 FROM activity_sources WHERE activity_id = $activityId)', { activityId: previousActivityId });
+            }
+            return;
+        }
+    }
+    if (source.external_id) {
+        await database.run(`INSERT INTO activity_links VALUES ($activitySourceId, $activityId, 'strong_external_id', 1.0, '{}', now())
+       ON CONFLICT (activity_source_id) DO UPDATE SET activity_id = excluded.activity_id, method = excluded.method, confidence = excluded.confidence, evidence_json = excluded.evidence_json, linked_at = now()`, { activitySourceId, activityId: source.activity_id });
+        return;
+    }
+    const candidates = await database.rows(`
+    SELECT source.activity_source_id, source.activity_id, source.provider, source.remote_activity_id, source.external_id,
+      activity.started_at_utc, activity.sport, summary.distance_m, summary.moving_s
+    FROM activity_sources source
+    JOIN activities activity USING (activity_id)
+    LEFT JOIN activity_summaries summary USING (activity_source_id)
+    WHERE source.activity_source_id <> $activitySourceId
+      AND source.provider <> $provider
+      AND activity.started_at_utc BETWEEN $startFloor AND $startCeiling
+  `, {
+        activitySourceId, provider: source.provider,
+        startFloor: new Date(timestamp(source.started_at_utc) - 90_000).toISOString(),
+        startCeiling: new Date(timestamp(source.started_at_utc) + 90_000).toISOString(),
+    });
+    const matched = candidates.map((candidate) => ({ candidate, result: qualifies(source, candidate) })).filter((item) => item.result !== null);
+    // A provider may already be strongly linked alongside a second source (for
+    // example Garmin plus Intervals). Those are one logical candidate, not an
+    // ambiguity that should prevent a matching Strava source from joining it.
+    const logicalMatches = new Map();
+    for (const match of matched) {
+        const previous = logicalMatches.get(match.candidate.activity_id);
+        if (!previous || match.result.score > previous.result.score)
+            logicalMatches.set(match.candidate.activity_id, match);
+    }
+    const uniqueMatches = [...logicalMatches.values()];
+    if (uniqueMatches.length !== 1) {
+        await database.run(`INSERT INTO activity_links VALUES ($activitySourceId, $activityId, 'source', NULL, $evidence, now())
+       ON CONFLICT (activity_source_id) DO UPDATE SET activity_id = excluded.activity_id, method = excluded.method, confidence = excluded.confidence, evidence_json = excluded.evidence_json, linked_at = now()`, { activitySourceId, activityId: source.activity_id, evidence: json({ candidates: uniqueMatches.length, matchingSources: matched.length, reason: uniqueMatches.length ? 'ambiguous' : 'no_qualifying_candidate' }) });
+        return;
+    }
+    const { candidate, result } = uniqueMatches[0];
+    const oldActivityId = source.activity_id;
+    await database.run('UPDATE activity_sources SET activity_id = $activityId WHERE activity_source_id = $activitySourceId', { activityId: candidate.activity_id, activitySourceId });
+    await database.run(`UPDATE activities SET link_state = 'fuzzy_high_confidence' WHERE activity_id = $activityId`, { activityId: candidate.activity_id });
+    await database.run(`INSERT INTO activity_links VALUES ($activitySourceId, $activityId, 'fuzzy_high_confidence', $confidence, $evidence, now())
+     ON CONFLICT (activity_source_id) DO UPDATE SET activity_id = excluded.activity_id, method = excluded.method, confidence = excluded.confidence, evidence_json = excluded.evidence_json, linked_at = now()`, { activitySourceId, activityId: candidate.activity_id, confidence: result.score, evidence: json({ ...result.evidence, matchedActivitySourceId: candidate.activity_source_id }) });
+    await database.run('DELETE FROM activities WHERE activity_id = $activityId AND NOT EXISTS (SELECT 1 FROM activity_sources WHERE activity_id = $activityId)', { activityId: oldActivityId });
+}
+export async function setManualActivityLink(database, activitySourceId, activityId) {
+    await database.run('UPDATE activity_sources SET activity_id = $activityId WHERE activity_source_id = $activitySourceId', { activityId, activitySourceId });
+    await database.run(`UPDATE activities SET link_state = 'manual' WHERE activity_id = $activityId`, { activityId });
+    await database.run(`INSERT INTO activity_links VALUES ($activitySourceId, $activityId, 'manual', 1.0, '{"command":"link"}', now())
+     ON CONFLICT (activity_source_id) DO UPDATE SET activity_id = excluded.activity_id, method = excluded.method, confidence = excluded.confidence, evidence_json = excluded.evidence_json, linked_at = now()`, { activitySourceId, activityId });
+}
+export async function unlinkActivitySource(database, activitySourceId) {
+    const source = (await database.rows('SELECT provider, remote_activity_id FROM activity_sources WHERE activity_source_id = $activitySourceId', { activitySourceId }))[0];
+    if (!source)
+        throw new Error(`No activity source exists for ${activitySourceId}.`);
+    const activityId = `${source.provider}:${source.remote_activity_id}`;
+    await database.run(`INSERT INTO activities (activity_id, link_state) VALUES ($activityId, 'unlinked') ON CONFLICT (activity_id) DO NOTHING`, { activityId });
+    await database.run('UPDATE activity_sources SET activity_id = $activityId WHERE activity_source_id = $activitySourceId', { activityId, activitySourceId });
+    await database.run(`UPDATE activity_links SET activity_id = $activityId, method = 'source', confidence = NULL, evidence_json = '{"command":"unlink"}', linked_at = now() WHERE activity_source_id = $activitySourceId`, { activityId, activitySourceId });
+}
+//# sourceMappingURL=linking.js.map

package/dist/elt/normalization/normalizers.d.ts

@@ -0,0 +1,5 @@
+import type { CatenceDatabase } from '../storage/database.js';
+import type { SourceEntity } from '../../contracts/staging.js';
+export declare function importSourceEntity(database: CatenceDatabase, entity: SourceEntity): Promise<void>;
+/** Re-evaluate source quality whenever an activity is imported or linked. */
+export declare function refreshActivityQuality(database: CatenceDatabase, activityId: string): Promise<void>;