catence 0.0.0 → 0.1.0

package/dist/core/query/wellness.js

@@ -0,0 +1,292 @@
+import { QueryValidationError } from './catalog.js';
+import { jsonSafe } from './repository.js';
+/**
+ * A small, intentionally opinionated layer over Catence's general query
+ * surface.  It keeps the common wellness/recovery questions compact while
+ * retaining the same normalized daily-health and canonical-training facts.
+ */
+export const WELLNESS_METRICS = [
+    'resting_hr_bpm',
+    'hrv_ms',
+    'sleep_seconds',
+    'sleep_score',
+    'stress',
+    'body_battery',
+    'readiness',
+    'spo2_pct',
+    'steps',
+    'training_load',
+    'activity_count',
+    'distance_m',
+    'moving_s',
+];
+const DEFAULT_BASELINE_METRICS = ['resting_hr_bpm', 'hrv_ms', 'sleep_score', 'stress', 'body_battery', 'training_load'];
+const DEFAULT_ANOMALY_METRICS = ['resting_hr_bpm', 'hrv_ms', 'sleep_score', 'stress', 'body_battery'];
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+function addDays(date, days) {
+    const timestamp = Date.parse(`${date}T00:00:00.000Z`);
+    return new Date(timestamp + days * 86_400_000).toISOString().slice(0, 10);
+}
+function subtractDays(date, days) {
+    return addDays(date, -days);
+}
+function mean(values) {
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function standardDeviation(values) {
+    const center = mean(values);
+    return Math.sqrt(values.reduce((sum, value) => sum + (value - center) ** 2, 0) / values.length);
+}
+function pearson(x, y) {
+    const xDeviation = standardDeviation(x);
+    const yDeviation = standardDeviation(y);
+    if (xDeviation === 0 || yDeviation === 0)
+        return null;
+    const xMean = mean(x);
+    const yMean = mean(y);
+    return x.reduce((sum, value, index) => sum + (value - xMean) * (y[index] - yMean), 0) / (x.length * xDeviation * yDeviation);
+}
+function ranks(values) {
+    const ordered = values.map((value, index) => ({ value, index })).sort((left, right) => left.value - right.value);
+    const result = new Array(values.length);
+    let index = 0;
+    while (index < ordered.length) {
+        let end = index;
+        while (end + 1 < ordered.length && ordered[end + 1].value === ordered[index].value)
+            end++;
+        const rank = (index + end + 2) / 2;
+        for (let cursor = index; cursor <= end; cursor++)
+            result[ordered[cursor].index] = rank;
+        index = end + 1;
+    }
+    return result;
+}
+function metricList(metrics, fallback) {
+    const selected = [...new Set(metrics?.length ? metrics : fallback)];
+    if (selected.length === 0 || selected.length > 12)
+        throw new QueryValidationError('Choose between one and twelve wellness metrics.');
+    for (const metric of selected) {
+        if (!WELLNESS_METRICS.includes(metric))
+            throw new QueryValidationError(`Unsupported wellness metric: ${metric}.`);
+    }
+    return selected;
+}
+function numberOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function dateRange(startDate, endDate) {
+    const dates = [];
+    for (let date = startDate; date <= endDate; date = addDays(date, 1))
+        dates.push(date);
+    return dates;
+}
+export class WellnessService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async correlate(request) {
+        this.assertMetric(request.metricA);
+        this.assertMetric(request.metricB);
+        const range = await this.resolveRange(request.startDate, request.endDate, 90);
+        const rows = await this.dailyRows(range.startDate, range.endDate);
+        const method = request.method ?? 'pearson';
+        const requestedLag = request.lagDays ?? 0;
+        if (!Number.isInteger(requestedLag) || requestedLag < -30 || requestedLag > 30)
+            throw new QueryValidationError('lagDays must be an integer from -30 to 30.');
+        const lags = request.scanLags ? Array.from({ length: 15 }, (_, index) => index - 7) : [requestedLag];
+        const results = lags.map((lagDays) => this.correlation(rows, request.metricA, request.metricB, lagDays, method));
+        const selected = request.scanLags
+            ? [...results].sort((left, right) => (right.correlation === null ? -1 : Math.abs(right.correlation)) - (left.correlation === null ? -1 : Math.abs(left.correlation)) || right.pairedDays - left.pairedDays)[0]
+            : results[0];
+        return jsonSafe({
+            data: request.scanLags ? { selected, scannedLags: results } : selected,
+            provenance: { relations: ['daily_health', 'canonical_activity_training'], dailyHealthProvider: 'Garmin when available' },
+            query: { ...request, startDate: range.startDate, endDate: range.endDate, method, lagDays: requestedLag, scanLags: request.scanLags ?? false },
+            caveats: [
+                'A positive lag pairs metricA on date D with metricB on D plus lagDays; correlation is descriptive, not causal.',
+                'Null or missing values are excluded pairwise. A day without training has zero training load only when a daily-health row exists; a wholly absent day remains missing.',
+            ],
+        });
+    }
+    async baselines(request) {
+        const metrics = metricList(request.metrics, DEFAULT_BASELINE_METRICS);
+        const windowDays = request.windowDays ?? 28;
+        if (!Number.isInteger(windowDays) || windowDays < 7 || windowDays > 365)
+            throw new QueryValidationError('windowDays must be an integer from 7 to 365.');
+        const range = await this.resolveRange(undefined, request.endDate, windowDays);
+        const rows = await this.dailyRows(range.startDate, range.endDate);
+        const data = metrics.map((metric) => {
+            const observations = rows.flatMap((row) => row[metric] === null ? [] : [{ date: row.date, value: row[metric] }]);
+            const values = observations.map((observation) => observation.value);
+            const latest = observations.at(-1) ?? null;
+            const average = values.length ? mean(values) : null;
+            const deviation = values.length > 1 ? standardDeviation(values) : null;
+            return {
+                metric,
+                observations: values.length,
+                missingDays: windowDays - values.length,
+                mean: average,
+                standardDeviation: deviation,
+                lowerBand: average === null || deviation === null ? null : average - deviation,
+                upperBand: average === null || deviation === null ? null : average + deviation,
+                latestDate: latest?.date ?? null,
+                latestValue: latest?.value ?? null,
+                latestZScore: latest === null || average === null || deviation === null || deviation === 0 ? null : (latest.value - average) / deviation,
+            };
+        });
+        return jsonSafe({
+            data,
+            provenance: { relations: ['daily_health', 'canonical_activity_training'], dailyHealthProvider: 'Garmin when available' },
+            query: { metrics, endDate: range.endDate, windowDays, startDate: range.startDate },
+            caveats: ['Baselines are descriptive trailing-window statistics, not medical or training recommendations.', 'Missing values are not treated as zero.'],
+        });
+    }
+    async anomalies(request) {
+        const metrics = metricList(request.metrics, DEFAULT_ANOMALY_METRICS);
+        const range = await this.resolveRange(request.startDate, request.endDate, 30);
+        const zThreshold = request.zThreshold ?? 2;
+        if (!Number.isFinite(zThreshold) || zThreshold < 1 || zThreshold > 5)
+            throw new QueryValidationError('zThreshold must be between 1 and 5.');
+        const rows = await this.dailyRows(range.startDate, range.endDate);
+        const flagged = new Map();
+        const summaries = metrics.map((metric) => {
+            const values = rows.map((row) => row[metric]).filter((value) => value !== null);
+            const average = values.length ? mean(values) : null;
+            const deviation = values.length > 1 ? standardDeviation(values) : null;
+            const anomalies = rows.flatMap((row) => {
+                const value = row[metric];
+                if (value === null || average === null || deviation === null || deviation === 0)
+                    return [];
+                const zScore = (value - average) / deviation;
+                if (Math.abs(zScore) < zThreshold)
+                    return [];
+                const anomaly = { metric, date: row.date, value, zScore, direction: zScore > 0 ? 'above_baseline' : 'below_baseline' };
+                flagged.set(row.date, [...(flagged.get(row.date) ?? []), anomaly]);
+                return [anomaly];
+            });
+            return { metric, observations: values.length, mean: average, standardDeviation: deviation, anomalies };
+        });
+        return jsonSafe({
+            data: {
+                metrics: summaries,
+                crossMetricDays: [...flagged.entries()].filter(([, items]) => items.length > 1).map(([date, items]) => ({ date, anomalies: items })),
+            },
+            provenance: { relations: ['daily_health', 'canonical_activity_training'], dailyHealthProvider: 'Garmin when available' },
+            query: { metrics, startDate: range.startDate, endDate: range.endDate, zThreshold },
+            caveats: ['Anomalies are statistical outliers in the selected period, not diagnoses or explanations.', 'Metrics with fewer than two observations, constant values, or missing days do not produce z-scores.'],
+        });
+    }
+    async coverage(request) {
+        const metrics = metricList(request.metrics, [...WELLNESS_METRICS]);
+        const range = await this.resolveRange(request.startDate, request.endDate, 90);
+        const rows = await this.dailyRows(range.startDate, range.endDate);
+        const byDate = new Map(rows.map((row) => [row.date, row]));
+        const dates = dateRange(range.startDate, range.endDate);
+        const data = metrics.map((metric) => {
+            const presentDates = dates.filter((date) => byDate.get(date)?.[metric] !== null);
+            return {
+                metric,
+                expectedDays: dates.length,
+                presentDays: presentDates.length,
+                missingDays: dates.length - presentDates.length,
+                firstPresentDate: presentDates[0] ?? null,
+                lastPresentDate: presentDates.at(-1) ?? null,
+                missingDates: dates.filter((date) => byDate.get(date)?.[metric] === null).slice(0, 100),
+                missingDatesTruncated: dates.length - presentDates.length > 100,
+            };
+        });
+        const errors = await this.repository.rows('SELECT count(*) AS count FROM normalization_errors WHERE resolved_at IS NULL');
+        return jsonSafe({
+            data: { metrics: data, unresolvedExtractionErrors: Number(errors[0]?.count ?? 0) },
+            provenance: { relations: ['daily_health', 'canonical_activity_training', 'normalization_errors'], dailyHealthProvider: 'Garmin when available' },
+            query: { metrics, startDate: range.startDate, endDate: range.endDate },
+            caveats: ['Coverage reports unavailable observations; it does not infer rest days, zero load, or negative health signals from missing records.', 'Only the first 100 missing dates per metric are returned.'],
+        });
+    }
+    assertMetric(metric) {
+        if (!WELLNESS_METRICS.includes(metric))
+            throw new QueryValidationError(`Unsupported wellness metric: ${metric}.`);
+    }
+    async resolveRange(startDate, endDate, defaultDays) {
+        const latest = await this.repository.rows(`
+      SELECT max(date) AS latest_date FROM (
+        SELECT metric_date AS date FROM daily_health
+        UNION ALL
+        SELECT cast(started_at_utc AS DATE) AS date FROM canonical_activity_training
+      ) AS known_dates
+    `);
+        const latestDate = latest[0]?.latest_date instanceof Date
+            ? latest[0].latest_date.toISOString().slice(0, 10)
+            : typeof latest[0]?.latest_date === 'string' ? latest[0].latest_date.slice(0, 10) : today();
+        const resolvedEndDate = endDate ?? latestDate;
+        const resolvedStartDate = startDate ?? subtractDays(resolvedEndDate, defaultDays - 1);
+        if (resolvedStartDate > resolvedEndDate)
+            throw new QueryValidationError('startDate must be on or before endDate.');
+        if (Date.parse(`${resolvedEndDate}T00:00:00Z`) - Date.parse(`${resolvedStartDate}T00:00:00Z`) > 730 * 86_400_000) {
+            throw new QueryValidationError('Wellness queries are limited to a two-year range. Narrow the requested dates.');
+        }
+        return { startDate: resolvedStartDate, endDate: resolvedEndDate };
+    }
+    async dailyRows(startDate, endDate) {
+        return this.repository.rows(`
+      WITH health AS (
+        SELECT cast(metric_date AS VARCHAR) AS date,
+          resting_hr_bpm, hrv_ms, sleep_seconds, sleep_score, stress, body_battery, readiness, spo2_pct, steps
+        FROM daily_health
+        WHERE metric_date BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE)
+      ), training AS (
+        SELECT cast(cast(started_at_utc AS DATE) AS VARCHAR) AS date,
+          sum(training_load) AS training_load,
+          count(*)::DOUBLE AS activity_count,
+          sum(distance_m) AS distance_m,
+          sum(moving_s) AS moving_s
+        FROM canonical_activity_training
+        WHERE cast(started_at_utc AS DATE) BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE)
+        GROUP BY 1
+      ), dates AS (
+        SELECT date FROM health UNION SELECT date FROM training
+      )
+      SELECT dates.date,
+        health.resting_hr_bpm, health.hrv_ms, health.sleep_seconds, health.sleep_score, health.stress,
+        health.body_battery, health.readiness, health.spo2_pct, health.steps,
+        CASE WHEN health.date IS NULL THEN NULL ELSE coalesce(training.training_load, 0) END AS training_load,
+        CASE WHEN health.date IS NULL THEN NULL ELSE coalesce(training.activity_count, 0) END AS activity_count,
+        CASE WHEN health.date IS NULL THEN NULL ELSE coalesce(training.distance_m, 0) END AS distance_m,
+        CASE WHEN health.date IS NULL THEN NULL ELSE coalesce(training.moving_s, 0) END AS moving_s
+      FROM dates
+      LEFT JOIN health USING (date)
+      LEFT JOIN training USING (date)
+      ORDER BY dates.date ASC
+    `, { startDate, endDate }).then((rows) => rows.map((row) => {
+            const normalized = { date: String(row.date) };
+            for (const metric of WELLNESS_METRICS)
+                normalized[metric] = numberOrNull(row[metric]);
+            return normalized;
+        }));
+    }
+    correlation(rows, metricA, metricB, lagDays, method) {
+        const byDate = new Map(rows.map((row) => [row.date, row]));
+        const pairs = rows.flatMap((row) => {
+            const other = byDate.get(addDays(row.date, lagDays));
+            const first = row[metricA];
+            const second = other?.[metricB] ?? null;
+            return first === null || second === null ? [] : [{ date: row.date, pairedDate: other.date, first, second }];
+        });
+        const x = pairs.map((pair) => pair.first);
+        const y = pairs.map((pair) => pair.second);
+        return {
+            metricA,
+            metricB,
+            lagDays,
+            method,
+            pairedDays: pairs.length,
+            correlation: pairs.length < 3 ? null : pearson(method === 'spearman' ? ranks(x) : x, method === 'spearman' ? ranks(y) : y),
+            firstPairedDate: pairs[0]?.date ?? null,
+            lastPairedDate: pairs.at(-1)?.date ?? null,
+        };
+    }
+}
+//# sourceMappingURL=wellness.js.map

package/dist/core/retrieval/index.d.ts

@@ -0,0 +1,13 @@
+import type { WriteDataStore } from '../../contracts/storage.js';
+import type { DataFilter } from '../query/analytics.js';
+import { ReadOnlyRepository } from '../query/repository.js';
+export declare function buildRetrievalIndex(database: WriteDataStore): Promise<{
+    documents: number;
+    mode: 'full_text' | 'keyword';
+    watermark: string | null;
+}>;
+export declare function searchContext(repository: ReadOnlyRepository, request: {
+    query: string;
+    filters?: DataFilter[];
+    limit?: number;
+}): Promise<Record<string, unknown>>;

package/dist/core/retrieval/index.js

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto';
+import { compileFilters } from '../query/analytics.js';
+import { getDataset, QueryValidationError } from '../query/catalog.js';
+import { jsonSafe } from '../query/repository.js';
+function short(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized ? normalized.slice(0, 2_000) : null;
+}
+function dateText(value) {
+    if (value instanceof Date)
+        return value.toISOString().slice(0, 10);
+    if (typeof value === 'string')
+        return value.slice(0, 10) || null;
+    return null;
+}
+function documentId(document) {
+    return createHash('sha256').update(`${document.entityType}\u0000${document.entityId}\u0000${document.text}`).digest('hex');
+}
+function words(...parts) {
+    return parts.filter((part) => Boolean(part)).join('. ').replace(/\s+/g, ' ').trim();
+}
+function payloadObject(value) {
+    if (typeof value === 'string') {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return {};
+        }
+    }
+    return value && typeof value === 'object' ? value : {};
+}
+function selectedPayloadText(payload) {
+    const fields = ['name', 'title', 'description', 'notes', 'note', 'message', 'text', 'tags', 'workoutName', 'routeName', 'eventName'];
+    return fields.flatMap((field) => {
+        const value = payload[field];
+        if (Array.isArray(value))
+            return value.map(short).filter((entry) => Boolean(entry));
+        const result = short(value);
+        return result ? [result] : [];
+    });
+}
+export async function buildRetrievalIndex(database) {
+    const documents = [];
+    const activities = await database.rows(`
+    SELECT summary.activity_source_id, source.activity_id, source.provider, cast(activity.started_at_utc AS DATE) AS occurred_on,
+      activity.name, activity.sport, summary.distance_m, summary.moving_s, summary.training_load, summary.avg_hr, summary.avg_power, summary.weighted_power, summary.calories, summary.metrics_json
+    FROM activity_summaries summary
+    JOIN activity_sources source USING (activity_source_id)
+    JOIN activities activity USING (activity_id)
+  `);
+    for (const activity of activities) {
+        const facts = [
+            activity.sport ? `sport ${activity.sport}` : null,
+            activity.distance_m ? `${Number(activity.distance_m).toFixed(0)} m` : null,
+            activity.moving_s ? `${Math.round(Number(activity.moving_s) / 60)} min moving` : null,
+            activity.training_load ? `training load ${activity.training_load}` : null,
+            activity.avg_hr ? `average heart rate ${activity.avg_hr} bpm` : null,
+            activity.avg_power ? `average power ${activity.avg_power} W` : null,
+            activity.calories ? `${activity.calories} kcal` : null,
+        ].filter(Boolean).join(', ');
+        const text = words(short(activity.name), facts ? `Activity summary: ${facts}` : null);
+        if (text)
+            documents.push({ entityType: 'activity', entityId: String(activity.activity_id), activitySourceId: String(activity.activity_source_id), provider: String(activity.provider), occurredOn: dateText(activity.occurred_on), text, metadata: { sport: activity.sport, name: activity.name } });
+    }
+    const intervals = await database.rows(`
+    SELECT intervals.activity_source_id, source.activity_id, source.provider, cast(activity.started_at_utc AS DATE) AS occurred_on,
+      intervals.interval_key, intervals.label, intervals.start_s, intervals.end_s, intervals.avg_power, intervals.avg_hr
+    FROM activity_intervals intervals JOIN activity_sources source USING (activity_source_id) JOIN activities activity USING (activity_id)
+  `);
+    for (const interval of intervals) {
+        const text = words(short(interval.label), `Interval ${interval.interval_key}`, interval.avg_power ? `average power ${interval.avg_power} W` : null, interval.avg_hr ? `average heart rate ${interval.avg_hr} bpm` : null);
+        documents.push({ entityType: 'activity_interval', entityId: `${interval.activity_source_id}:${interval.interval_key}`, activitySourceId: String(interval.activity_source_id), provider: String(interval.provider), occurredOn: dateText(interval.occurred_on), text, metadata: { activityId: interval.activity_id, label: interval.label } });
+    }
+    const nutritionDays = await database.rows('SELECT provider, cast(nutrition_date AS VARCHAR) AS nutrition_date, energy_kcal, carbohydrates_g, protein_g, fat_g, hydration_ml FROM nutrition_days');
+    for (const day of nutritionDays) {
+        const parts = [day.energy_kcal ? `${day.energy_kcal} kcal` : null, day.carbohydrates_g ? `${day.carbohydrates_g} g carbohydrate` : null, day.protein_g ? `${day.protein_g} g protein` : null, day.fat_g ? `${day.fat_g} g fat` : null, day.hydration_ml ? `${day.hydration_ml} ml hydration` : null];
+        documents.push({ entityType: 'nutrition_day', entityId: `${day.provider}:${dateText(day.nutrition_date)}`, provider: String(day.provider), occurredOn: dateText(day.nutrition_date), text: words('Nutrition summary', ...parts), metadata: {} });
+    }
+    const nutritionItems = await database.rows('SELECT provider, remote_item_id, cast(nutrition_date AS VARCHAR) AS nutrition_date, meal, food_name, energy_kcal, carbohydrates_g, protein_g, fat_g FROM nutrition_items');
+    for (const item of nutritionItems) {
+        const text = words(short(item.food_name), short(item.meal), item.energy_kcal ? `${item.energy_kcal} kcal` : null, item.carbohydrates_g ? `${item.carbohydrates_g} g carbohydrate` : null, item.protein_g ? `${item.protein_g} g protein` : null);
+        if (text)
+            documents.push({ entityType: 'nutrition_item', entityId: `${item.provider}:${item.remote_item_id}`, provider: String(item.provider), occurredOn: dateText(item.nutrition_date), text, metadata: { meal: item.meal, foodName: item.food_name } });
+    }
+    const domain = await database.rows(`
+    SELECT provider, entity_type, remote_id, cast(occurred_on AS VARCHAR) AS occurred_on, payload_json
+    FROM domain_entities
+    WHERE entity_type IN ('event', 'workout', 'scheduled_workout', 'training_plan', 'route', 'message')
+  `);
+    for (const entity of domain) {
+        const fields = selectedPayloadText(payloadObject(entity.payload_json));
+        const entityType = String(entity.entity_type);
+        if (fields.length)
+            documents.push({ entityType, entityId: String(entity.remote_id), provider: String(entity.provider), occurredOn: dateText(entity.occurred_on), text: words(`${entityType.replaceAll('_', ' ')}`, ...fields), metadata: {} });
+    }
+    const weekly = await database.rows(`
+    SELECT date_trunc('week', started_at_utc)::DATE AS week, count(*)::INTEGER AS activities, sum(moving_s) AS moving_s, sum(training_load) AS training_load
+    FROM canonical_activity_training GROUP BY 1
+  `);
+    for (const week of weekly) {
+        const weekDate = dateText(week.week);
+        if (weekDate)
+            documents.push({ entityType: 'weekly_training_summary', entityId: weekDate, occurredOn: weekDate, text: words(`Week beginning ${weekDate}`, `${week.activities} activities`, week.moving_s ? `${Math.round(Number(week.moving_s) / 60)} minutes training` : null, week.training_load ? `training load ${week.training_load}` : null), metadata: {} });
+    }
+    const trainingMetrics = await database.rows(`
+    SELECT observation_id, provider, metric_name, sport, device_id, cast(observed_at AS VARCHAR) AS observed_at,
+      value_number, value_text, unit, source_type
+    FROM training_metric_observations
+  `);
+    for (const metric of trainingMetrics) {
+        const value = metric.value_number !== null && metric.value_number !== undefined
+            ? `${metric.value_number}${metric.unit ? ` ${metric.unit}` : ''}`
+            : short(metric.value_text);
+        const text = words(String(metric.metric_name).replaceAll('_', ' '), value ? `value ${value}` : null, metric.sport ? `sport ${metric.sport}` : null, metric.device_id ? `device ${metric.device_id}` : null, metric.source_type ? `source ${metric.source_type}` : null);
+        if (text)
+            documents.push({
+                entityType: 'training_metric', entityId: String(metric.observation_id), provider: String(metric.provider),
+                occurredOn: dateText(metric.observed_at), text, metadata: { metricName: metric.metric_name, sport: metric.sport, deviceId: metric.device_id },
+            });
+    }
+    const deduplicated = new Map(documents.map((document) => [documentId(document), document]));
+    const watermarkRows = await database.rows('SELECT max(cast(fetched_at AS VARCHAR)) AS watermark FROM raw_objects');
+    const watermark = watermarkRows[0]?.watermark ?? null;
+    let mode = 'keyword';
+    await database.run('BEGIN TRANSACTION');
+    try {
+        await database.run('DELETE FROM retrieval_documents');
+        for (const document of deduplicated.values()) {
+            const id = documentId(document);
+            await database.run(`INSERT INTO retrieval_documents (document_id, entity_type, entity_id, activity_source_id, provider, occurred_on, document_text, metadata_json, content_hash)
+        VALUES ($id, $entityType, $entityId, $activitySourceId, $provider, $occurredOn, $text, $metadata, $hash)`, {
+                id, entityType: document.entityType, entityId: document.entityId, activitySourceId: document.activitySourceId ?? null, provider: document.provider ?? null, occurredOn: document.occurredOn || null, text: document.text, metadata: JSON.stringify(document.metadata), hash: id,
+            });
+        }
+        await database.run(`INSERT INTO retrieval_index_state (index_name, status, mode, source_watermark, built_at, detail_json)
+      VALUES ('context', 'ready', $mode, $watermark, now(), $detail)
+      ON CONFLICT (index_name) DO UPDATE SET status = excluded.status, mode = excluded.mode, source_watermark = excluded.source_watermark, built_at = excluded.built_at, detail_json = excluded.detail_json`, {
+            mode, watermark, detail: JSON.stringify({ documentCount: deduplicated.size }),
+        });
+        await database.run('COMMIT');
+    }
+    catch (error) {
+        await database.run('ROLLBACK');
+        throw error;
+    }
+    mode = await tryBuildFts(database);
+    if (mode === 'full_text') {
+        await database.run("UPDATE retrieval_index_state SET mode = 'full_text' WHERE index_name = 'context'");
+    }
+    return { documents: deduplicated.size, mode, watermark };
+}
+async function tryBuildFts(database) {
+    try {
+        // No INSTALL: extensions must already be local.  Failure intentionally falls back to keyword search.
+        await database.run('LOAD fts');
+        try {
+            await database.run("PRAGMA drop_fts_index('retrieval_documents')");
+        }
+        catch { /* index may not exist */ }
+        await database.run("PRAGMA create_fts_index('retrieval_documents', 'document_id', 'document_text')");
+        await database.rows("SELECT fts_main_retrieval_documents.match_bm25(document_id, 'catence') AS score FROM retrieval_documents LIMIT 1");
+        return 'full_text';
+    }
+    catch {
+        return 'keyword';
+    }
+}
+export async function searchContext(repository, request) {
+    const query = request.query.trim();
+    if (query.length < 2 || query.length > 500)
+        throw new QueryValidationError('search_context requires a 2–500 character query.');
+    const limit = Math.min(Math.max(request.limit ?? 10, 1), 50);
+    const state = await repository.rows("SELECT mode, status FROM retrieval_index_state WHERE index_name = 'context'");
+    const { where, values } = compileFilters(getDataset('source_entities'), [], undefined, undefined); // Creates a parameter-safe empty baseline; retrieval has its own filter allowlist below.
+    void where;
+    void values;
+    const metadataClauses = [];
+    const params = { query, limit };
+    for (const [index, filter] of (request.filters ?? []).entries()) {
+        if (!['provider', 'entity_type', 'occurred_on'].includes(filter.column) || !['eq', 'between', 'in'].includes(filter.op))
+            throw new QueryValidationError('search_context permits only provider, entity_type, and occurred_on eq/in/between filters.');
+        const column = `"${filter.column}"`;
+        const key = `filter${index}`;
+        if (filter.op === 'eq') {
+            metadataClauses.push(`${column} = $${key}`);
+            params[key] = filter.value;
+        }
+        else if (filter.op === 'between') {
+            if (!Array.isArray(filter.value) || filter.value.length !== 2)
+                throw new QueryValidationError('between requires two values.');
+            metadataClauses.push(`${column} BETWEEN $${key}a AND $${key}b`);
+            params[`${key}a`] = filter.value[0];
+            params[`${key}b`] = filter.value[1];
+        }
+        else {
+            if (!Array.isArray(filter.value) || filter.value.length === 0 || filter.value.length > 100)
+                throw new QueryValidationError('in requires 1–100 values.');
+            const placeholders = filter.value.map((value, itemIndex) => { const itemKey = `${key}_${itemIndex}`; params[itemKey] = value; return `$${itemKey}`; });
+            metadataClauses.push(`${column} IN (${placeholders.join(', ')})`);
+        }
+    }
+    const filterSql = metadataClauses.length ? ` AND ${metadataClauses.join(' AND ')}` : '';
+    const terms = query.split(/\s+/).filter(Boolean).slice(0, 12);
+    const keywordScore = terms.map((_, index) => `CASE WHEN lower(document_text) LIKE '%' || lower($term${index}) || '%' THEN 1 ELSE 0 END`).join(' + ');
+    terms.forEach((term, index) => { params[`term${index}`] = term; });
+    let rows;
+    let mode = 'keyword';
+    if (state[0]?.mode === 'full_text') {
+        try {
+            rows = await repository.rows(`SELECT document_id, entity_type, entity_id, activity_source_id, provider, occurred_on, left(document_text, 600) AS snippet, fts_main_retrieval_documents.match_bm25(document_id, $query) AS score FROM retrieval_documents WHERE fts_main_retrieval_documents.match_bm25(document_id, $query) IS NOT NULL${filterSql} ORDER BY score DESC LIMIT $limit`, params);
+            mode = 'full_text';
+        }
+        catch { /* a stale or unsupported local FTS extension safely uses the keyword path */ }
+    }
+    if (!rows) {
+        const { query: ignoredQuery, ...keywordParams } = params;
+        void ignoredQuery;
+        rows = await repository.rows(`SELECT document_id, entity_type, entity_id, activity_source_id, provider, occurred_on, left(document_text, 600) AS snippet, (${keywordScore}) AS score FROM retrieval_documents WHERE (${keywordScore}) > 0${filterSql} ORDER BY score DESC, occurred_on DESC NULLS LAST, document_id ASC LIMIT $limit`, keywordParams);
+    }
+    const indexStatus = state[0]?.status ?? 'stale';
+    const indexIsFresh = indexStatus === 'ready';
+    return jsonSafe({
+        data: rows.map((row) => ({ ...row, recommendedFollowUpTool: recommendedTool(String(row.entity_type)) })),
+        retrievalIndex: {
+            status: indexStatus,
+            fresh: indexIsFresh,
+            authoritativeAlternative: indexIsFresh ? null : 'Use find_activities or query_read_only_data for authoritative activity discovery until the index is rebuilt.',
+        },
+        provenance: { dataset: 'retrieval_documents', mode, indexStatus },
+        query: { query, filters: request.filters ?? [], limit },
+        caveats: !indexIsFresh
+            ? ['Index stale; use direct activity query (find_activities or query_read_only_data) for authoritative results. Run catence-data build-retrieval-index after sync.']
+            : ['Search results are context pointers; use the recommended tool for authoritative numeric facts.'],
+    });
+}
+function recommendedTool(entityType) {
+    if (entityType.startsWith('activity'))
+        return 'find_activities';
+    if (entityType.startsWith('nutrition'))
+        return 'aggregate_data';
+    if (entityType === 'weekly_training_summary' || entityType === 'training_metric')
+        return 'aggregate_data';
+    return 'query_read_only_data';
+}
+//# sourceMappingURL=index.js.map

package/dist/core/runtime/configuration.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import type { CatencePaths } from '../../contracts/runtime.js';
+export type { CatencePaths } from '../../contracts/runtime.js';
+export declare function resolvePaths(root?: string): CatencePaths;
+export declare function ensurePaths(paths: CatencePaths): Promise<void>;
+export declare function defaultFromDate(now?: Date): string;
+export declare function requireIntervalsConfig(): {
+    apiKey: string;
+    athleteId: string;
+};
+declare const rateLimitSchema: z.ZodObject<{
+    requests: z.ZodNumber;
+    windowSeconds: z.ZodNumber;
+}, z.core.$strict>;
+declare const catenceConfigSchema: z.ZodObject<{
+    mcp: z.ZodOptional<z.ZodObject<{
+        rateLimits: z.ZodOptional<z.ZodObject<{
+            server: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                requests: z.ZodNumber;
+                windowSeconds: z.ZodNumber;
+            }, z.core.$strict>>>;
+            tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+                requests: z.ZodNumber;
+                windowSeconds: z.ZodNumber;
+            }, z.core.$strict>>>>;
+            resources: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+                requests: z.ZodNumber;
+                windowSeconds: z.ZodNumber;
+            }, z.core.$strict>>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    providers: z.ZodOptional<z.ZodObject<{
+        strava: z.ZodOptional<z.ZodObject<{
+            budget: z.ZodOptional<z.ZodObject<{
+                maxConcurrentRequests: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                readRequestsPer15Minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                readRequestsPerDay: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    console: z.ZodOptional<z.ZodObject<{
+        defaultProfile: z.ZodOptional<z.ZodString>;
+        limits: z.ZodOptional<z.ZodObject<{
+            toolRounds: z.ZodOptional<z.ZodNumber>;
+            toolResultCharacters: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                label: z.ZodOptional<z.ZodString>;
+                model: z.ZodString;
+            }, z.core.$strict>>>;
+            defaultModel: z.ZodOptional<z.ZodString>;
+            defaultReasoningEffort: z.ZodOptional<z.ZodEnum<{
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+            }>>;
+            apiKeyEnv: z.ZodOptional<z.ZodString>;
+            apiBaseEnv: z.ZodOptional<z.ZodString>;
+            apiVersionEnv: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CatenceConfig = z.infer<typeof catenceConfigSchema>;
+export type ConfigRateLimit = z.infer<typeof rateLimitSchema>;
+export declare function loadCatenceConfig(paths: CatencePaths): Promise<CatenceConfig>;
+export declare function configuredMcpRateLimit(config: CatenceConfig, type: 'tools' | 'resources', name: string): ConfigRateLimit | null;