catence 0.0.0 → 0.2.0-beta.1

package/dist/core/query/fitness.d.ts

@@ -0,0 +1,40 @@
+import { ReadOnlyRepository } from './repository.js';
+export type FitnessDateRange = {
+    startDate?: string;
+    endDate?: string;
+};
+export type FtpHistoryRequest = FitnessDateRange & {
+    sport?: string;
+    sourcePreference?: 'settings' | 'settings_then_activity' | 'all';
+};
+export type Vo2MaxHistoryRequest = FitnessDateRange & {
+    sport?: string;
+};
+export type PowerSportFamily = 'cycling' | 'running';
+type PowerSportSelection = {
+    sport?: string;
+    sportFamily?: PowerSportFamily;
+};
+export type PowerCurveTrendRequest = FitnessDateRange & PowerSportSelection & {
+    durations?: number[];
+    sourceQuality?: 'all' | 'garmin_fit_derived';
+};
+export type PowerCoverageReportRequest = FitnessDateRange & PowerSportSelection & {
+    sourceQuality?: 'all' | 'garmin_fit_derived';
+};
+export type LatestCyclingActivitiesRequest = FitnessDateRange & {
+    includeMultisport?: boolean;
+    limit?: number;
+};
+/** Read-only, source-aware fitness projections built on normalized facts. */
+export declare class FitnessService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    ftpHistory(request?: FtpHistoryRequest): Promise<Record<string, unknown>>;
+    vo2MaxHistory(request?: Vo2MaxHistoryRequest): Promise<Record<string, unknown>>;
+    powerCurveTrend(request?: PowerCurveTrendRequest): Promise<Record<string, unknown>>;
+    powerCoverageReport(request?: PowerCoverageReportRequest): Promise<Record<string, unknown>>;
+    latestCyclingActivities(request?: LatestCyclingActivitiesRequest): Promise<Record<string, unknown>>;
+    cyclingProgressReport(request?: FitnessDateRange): Promise<Record<string, unknown>>;
+}
+export {};

package/dist/core/query/fitness.js

@@ -0,0 +1,297 @@
+import { QueryValidationError } from './catalog.js';
+const CYCLING_SPORTS = ['cycling', 'road_biking', 'indoor_cycling', 'virtual_ride'];
+const DEFAULT_POWER_DURATIONS = [5, 60, 300, 1_200, 1_800];
+const RUNNING_VO2MAX_ALIASES = new Set(['run', 'running']);
+function addDateRange(column, request, values) {
+    const clauses = [];
+    if (request.startDate) {
+        values.startDate = request.startDate;
+        clauses.push(`${column} >= cast($startDate AS TIMESTAMPTZ)`);
+    }
+    if (request.endDate) {
+        values.endDate = `${request.endDate}T23:59:59.999Z`;
+        clauses.push(`${column} <= cast($endDate AS TIMESTAMPTZ)`);
+    }
+    return clauses;
+}
+function cyclingSportClause(column, sport, values) {
+    if (!sport || sport.toLowerCase() === 'cycling')
+        return `lower(${column}) IN (${CYCLING_SPORTS.map((item) => `'${item}'`).join(', ')})`;
+    values.sport = sport;
+    return `lower(${column}) = lower($sport)`;
+}
+function powerSportClause(column, selection, values) {
+    if (selection.sport && selection.sportFamily)
+        throw new QueryValidationError('Choose either sport or sportFamily, not both.');
+    if (selection.sport) {
+        values.sport = selection.sport;
+        return `lower(${column}) = lower($sport)`;
+    }
+    if (selection.sportFamily === 'cycling')
+        return `lower(${column}) IN (${CYCLING_SPORTS.map((item) => `'${item}'`).join(', ')})`;
+    if (selection.sportFamily === 'running')
+        return `lower(${column}) LIKE '%run%'`;
+    throw new QueryValidationError('power queries require an explicit sport or sportFamily.');
+}
+function durationLabel(duration) {
+    if (duration < 60)
+        return `${duration} s`;
+    if (duration % 60 === 0)
+        return `${duration / 60} min`;
+    return `${Math.floor(duration / 60)} min ${duration % 60} s`;
+}
+function sourceRank(sourceType) {
+    if (sourceType === 'cycling_ftp_history')
+        return 0;
+    if (sourceType === 'cycling_ftp')
+        return 1;
+    if (sourceType === 'activity_summary')
+        return 2;
+    return 3;
+}
+function sourceTypeFilter(preference) {
+    if (preference === 'settings')
+        return "AND source_type IN ('cycling_ftp_history', 'cycling_ftp')";
+    if (preference === 'settings_then_activity')
+        return "AND source_type IN ('cycling_ftp_history', 'cycling_ftp', 'activity_summary')";
+    return '';
+}
+/** Read-only, source-aware fitness projections built on normalized facts. */
+export class FitnessService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async ftpHistory(request = {}) {
+        const sourcePreference = request.sourcePreference ?? 'settings_then_activity';
+        const values = {};
+        const clauses = ["metric_name = 'cycling_ftp_w'", cyclingSportClause('sport', request.sport ?? 'cycling', values), ...addDateRange('observed_at', request, values)];
+        const observations = await this.repository.rows(`
+      SELECT observation_id, cast(observed_at AS VARCHAR) AS observed_at, value_number, value_text, unit, sport,
+        source_type, source_remote_id, activity_source_id, raw_object_hash
+      FROM training_metric_observations
+      WHERE ${clauses.join(' AND ')} ${sourceTypeFilter(sourcePreference)}
+      ORDER BY observed_at ASC,
+        CASE source_type WHEN 'cycling_ftp_history' THEN 0 WHEN 'cycling_ftp' THEN 1 WHEN 'activity_summary' THEN 2 ELSE 3 END,
+        observation_id ASC
+    `, values);
+        const seriesByDate = new Map();
+        for (const observation of observations) {
+            const date = observation.observed_at.slice(0, 10);
+            const current = seriesByDate.get(date);
+            if (!current || sourceRank(observation.source_type) < sourceRank(current.source_type))
+                seriesByDate.set(date, observation);
+        }
+        return {
+            data: { observations, preferredSeries: [...seriesByDate.values()] },
+            provenance: { dataset: 'training_metric_observations', metric: 'cycling_ftp_w', sourcePreference },
+            query: { ...request, sport: request.sport ?? 'cycling', sourcePreference },
+            caveats: [
+                'FTP settings, the direct current-setting endpoint, and activity-summary FTP are retained as distinct source types.',
+                ...(observations.length === 0 ? ['No matching normalized FTP observations are available for this range.'] : []),
+            ],
+        };
+    }
+    async vo2MaxHistory(request = {}) {
+        if (!request.sport) {
+            const values = {};
+            const clauses = ["metric_name = 'vo2_max_ml_kg_min'", ...addDateRange('observed_at', request, values)];
+            const availableSports = await this.repository.rows(`
+        WITH ranked AS (
+          SELECT sport, value_number, observed_at,
+            count(*) OVER (PARTITION BY sport)::INTEGER AS count,
+            row_number() OVER (PARTITION BY sport ORDER BY observed_at DESC, observation_id DESC) AS latest_rank
+          FROM training_metric_observations
+          WHERE ${clauses.join(' AND ')}
+        )
+        SELECT sport, max(count)::INTEGER AS count,
+          max(value_number) FILTER (WHERE latest_rank = 1) AS latest,
+          cast(max(observed_at) FILTER (WHERE latest_rank = 1) AS VARCHAR) AS latest_observed_at
+        FROM ranked GROUP BY sport ORDER BY sport ASC
+      `, values);
+            return {
+                data: {
+                    availableSports,
+                    sportAliases: [{ requestedSport: 'running', sourceSport: 'generic', reason: 'Garmin labels its running VO₂max estimate as generic.' }],
+                    actionRequired: 'Choose a sport explicitly. Use running for Garmin running VO₂max.',
+                },
+                provenance: { dataset: 'training_metric_observations', metric: 'vo2_max_ml_kg_min' },
+                query: { ...request, sport: null },
+                caveats: [
+                    'No VO₂max observations are returned until sport is chosen explicitly; Catence never silently defaults to cycling.',
+                    'For a running request, Catence reads Garmin’s generic source-labelled VO₂max series and retains generic on each returned observation.',
+                ],
+            };
+        }
+        const requestedSport = request.sport;
+        const sourceSport = RUNNING_VO2MAX_ALIASES.has(requestedSport.trim().toLowerCase()) ? 'generic' : requestedSport;
+        const values = { sourceSport };
+        const clauses = ["metric_name = 'vo2_max_ml_kg_min'", 'lower(sport) = lower($sourceSport)', ...addDateRange('observed_at', request, values)];
+        const observations = await this.repository.rows(`
+      SELECT observation_id, cast(observed_at AS VARCHAR) AS observed_at, value_number, value_text, unit, sport,
+        source_type, source_remote_id, activity_source_id, raw_object_hash
+      FROM training_metric_observations
+      WHERE ${clauses.join(' AND ')}
+      ORDER BY observed_at ASC, observation_id ASC
+    `, values);
+        return {
+            data: observations,
+            provenance: { dataset: 'training_metric_observations', metric: 'vo2_max_ml_kg_min', requestedSport, sourceSport },
+            query: { ...request, sport: requestedSport, sourceSport },
+            caveats: [
+                'Sport values on observations are reported exactly as Garmin supplied them; generic and cycling values are never combined.',
+                ...(sourceSport === 'generic' && requestedSport !== 'generic' ? ['Garmin supplies running VO₂max under the generic source label; the returned rows preserve that raw label.'] : []),
+                ...(observations.length === 0 ? [`No normalized ${requestedSport} VO₂max history is available for this range.`] : []),
+            ],
+        };
+    }
+    async powerCurveTrend(request = {}) {
+        const durations = [...new Set(request.durations ?? DEFAULT_POWER_DURATIONS)].sort((left, right) => left - right);
+        if (durations.length === 0 || durations.length > 12 || durations.some((duration) => !Number.isInteger(duration) || duration < 1 || duration > 86_400)) {
+            throw new QueryValidationError('durations must contain 1–12 whole-second values between 1 and 86,400.');
+        }
+        const sourceQuality = request.sourceQuality ?? 'all';
+        const values = {};
+        const durationPlaceholders = durations.map((duration, index) => {
+            const key = `duration${index}`;
+            values[key] = duration;
+            return `$${key}`;
+        });
+        const clauses = [powerSportClause('sport', request, values), `duration_s IN (${durationPlaceholders.join(', ')})`, ...addDateRange('started_at_utc', request, values)];
+        if (sourceQuality !== 'all')
+            clauses.push("source_type = 'garmin_fit_derived'");
+        const rows = await this.repository.rows(`
+      WITH ranked AS (
+        SELECT cast(date_trunc('month', started_at_utc) AS VARCHAR) AS month, duration_s, best_power_w,
+          activity_id, activity_source_id, cast(started_at_utc AS VARCHAR) AS started_at_utc, sport, source_type, raw_object_hash,
+          row_number() OVER (
+            PARTITION BY date_trunc('month', started_at_utc), duration_s
+            ORDER BY best_power_w DESC, started_at_utc ASC, activity_source_id ASC
+          ) AS source_rank
+        FROM power_best_facts
+        WHERE ${clauses.join(' AND ')}
+      )
+      SELECT * EXCLUDE (source_rank) FROM ranked WHERE source_rank = 1
+      ORDER BY month ASC, duration_s ASC
+    `, values);
+        return {
+            data: rows.map((row) => ({ ...row, durationLabel: durationLabel(row.duration_s) })),
+            provenance: { dataset: 'power_best_facts', sourceQuality },
+            query: { ...request, durations, sourceQuality, aggregation: 'monthly maximum per duration' },
+            caveats: [
+                'Values are duration-labelled Garmin FIT-derived power bests; each month/duration row identifies its supporting activity.',
+                ...(rows.length === 0 ? ['No normalized power-best observations matched the requested durations and range.'] : []),
+            ],
+        };
+    }
+    async powerCoverageReport(request = {}) {
+        const sourceQuality = request.sourceQuality ?? 'garmin_fit_derived';
+        const values = {};
+        const activityClauses = [powerSportClause('activity.sport', request, values), ...addDateRange('activity.started_at_utc', request, values)];
+        const bestClause = sourceQuality === 'garmin_fit_derived' ? "WHERE best.source_type = 'garmin_fit_derived'" : '';
+        const scoped = `
+      WITH source_activities AS (
+        SELECT source.activity_source_id, activity.started_at_utc, activity.sport
+        FROM activity_sources AS source
+        JOIN activities AS activity USING (activity_id)
+        WHERE ${activityClauses.join(' AND ')}
+      ), scoped_bests AS (
+        SELECT best.activity_source_id, best.duration_s, best.best_power_w, best.source_type
+        FROM activity_power_bests AS best
+        JOIN source_activities USING (activity_source_id)
+        ${bestClause}
+      )
+    `;
+        const [activityCoverage, durationInventory] = await Promise.all([
+            this.repository.rows(`${scoped}
+        SELECT sport, count(DISTINCT source_activities.activity_source_id)::INTEGER AS activities,
+          count(DISTINCT scoped_bests.activity_source_id)::INTEGER AS powered_activities,
+          count(scoped_bests.duration_s)::INTEGER AS datapoints,
+          cast(min(started_at_utc) AS VARCHAR) AS first_activity_at,
+          cast(max(started_at_utc) AS VARCHAR) AS last_activity_at
+        FROM source_activities
+        LEFT JOIN scoped_bests USING (activity_source_id)
+        GROUP BY sport
+        ORDER BY sport`, values),
+            this.repository.rows(`${scoped}
+        SELECT duration_s, count(*)::INTEGER AS datapoints,
+          count(DISTINCT activity_source_id)::INTEGER AS activities,
+          min(best_power_w) AS min_power_w, max(best_power_w) AS max_power_w
+        FROM scoped_bests
+        GROUP BY duration_s
+        ORDER BY duration_s`, values),
+        ]);
+        return {
+            data: { activityCoverage, durationInventory: durationInventory.map((row) => ({ ...row, durationLabel: durationLabel(row.duration_s) })) },
+            provenance: { activityDataset: 'activities', powerDataset: 'power_best_facts', sourceQuality },
+            query: { ...request, sourceQuality },
+            caveats: [
+                'Coverage is based on FIT-derived per-activity duration bests, never sparse activity-summary average power.',
+                'Short-duration maxima can include sensor spikes; inspect the supporting activity stream before treating an extreme as physiological.',
+                'Raw activity samples remain scoped to one activity source at a time and may paginate.',
+            ],
+        };
+    }
+    async latestCyclingActivities(request = {}) {
+        const limit = Math.min(Math.max(request.limit ?? 20, 1), 100);
+        const values = { includeMultisport: request.includeMultisport ?? false, limit };
+        const sportClause = cyclingSportClause('activity.sport', 'cycling', values);
+        const clauses = [`(${sportClause} OR ($includeMultisport AND lower(activity.sport) = 'multi_sport'))`, ...addDateRange('activity.started_at_utc', request, values)];
+        const rows = await this.repository.rows(`
+      SELECT source.activity_id, source.activity_source_id, source.remote_activity_id,
+        cast(activity.started_at_utc AS VARCHAR) AS started_at_utc, activity.sport, activity.name, activity.link_state,
+        raw.parent_remote_id, summary.distance_m, summary.moving_s, summary.elapsed_s, summary.elevation_gain_m,
+        summary.avg_hr, summary.avg_power, summary.training_load, manifest.row_count AS stream_rows, source.raw_object_hash
+      FROM activity_sources AS source
+      JOIN activities AS activity USING (activity_id)
+      LEFT JOIN activity_summaries AS summary USING (activity_source_id)
+      LEFT JOIN source_entities AS raw ON raw.provider = source.provider AND raw.entity_type = 'activity' AND raw.remote_id = source.remote_activity_id
+      LEFT JOIN stream_manifest AS manifest ON manifest.provider = source.provider AND manifest.activity_source_id = source.activity_source_id
+      WHERE source.provider = 'garmin' AND ${clauses.join(' AND ')}
+      ORDER BY activity.started_at_utc DESC, source.activity_source_id ASC
+      LIMIT $limit
+    `, values);
+        return {
+            data: rows.map((row) => ({
+                ...row,
+                isMultisportParent: row.sport.toLowerCase() === 'multi_sport',
+                parentActivityRemoteId: row.parent_remote_id,
+                streamAvailable: Number(row.stream_rows ?? 0) > 0,
+            })),
+            provenance: { relations: ['activities', 'activity_sources', 'activity_summaries', 'source_entities', 'stream_manifest'], provider: 'garmin' },
+            query: { ...request, includeMultisport: request.includeMultisport ?? false, limit },
+            caveats: [
+                'The projection uses Garmin source records only, avoiding duplicate Intervals summaries for the same linked activity.',
+                ...(request.includeMultisport ? ['Multisport parent summaries are flagged and are not represented as cycling-only component metrics.'] : []),
+            ],
+        };
+    }
+    async cyclingProgressReport(request = {}) {
+        const values = {};
+        const clauses = [cyclingSportClause('sport', 'cycling', values), ...addDateRange('started_at_utc', request, values)];
+        const [ftp, vo2max, powerCurve, monthlyVolume] = await Promise.all([
+            this.ftpHistory({ ...request, sport: 'cycling' }),
+            this.vo2MaxHistory({ ...request, sport: 'cycling' }),
+            this.powerCurveTrend({ ...request, sport: 'cycling' }),
+            this.repository.rows(`
+        SELECT cast(date_trunc('month', started_at_utc) AS VARCHAR) AS month,
+          count(*)::INTEGER AS activities, sum(distance_m) AS distance_m, sum(moving_s) AS moving_s,
+          sum(training_load) AS training_load
+        FROM canonical_activity_training
+        WHERE ${clauses.join(' AND ')}
+        GROUP BY date_trunc('month', started_at_utc)
+        ORDER BY month ASC
+      `, values),
+        ]);
+        return {
+            data: { ftp, vo2max, powerCurve, monthlyVolume },
+            provenance: { relations: ['training_metric_observations', 'power_best_facts', 'canonical_activity_training'] },
+            query: request,
+            caveats: [
+                'This is a descriptive, source-aware report—not a physiological performance model.',
+                'FTP settings, VO₂max snapshots, volume/load, and power bests retain their individual provenance in the nested results.',
+            ],
+        };
+    }
+}
+//# sourceMappingURL=fitness.js.map

package/dist/core/query/repository.d.ts

@@ -0,0 +1,19 @@
+import type { CatencePaths } from '../../contracts/runtime.js';
+import type { QueryValues, ReadDataStore } from '../../contracts/storage.js';
+import { type DatasetDefinition } from './catalog.js';
+export declare class ReadOnlyRepository {
+    readonly database: ReadDataStore;
+    readonly paths: CatencePaths;
+    constructor(database: ReadDataStore, paths: CatencePaths);
+    close(): Promise<void>;
+    rows<T extends Record<string, unknown>>(sql: string, values?: QueryValues): Promise<T[]>;
+    datasetRelation(datasetName: string): Promise<string>;
+    activitySampleRelation(): Promise<string>;
+    status(): Promise<Record<string, unknown>>;
+    coverage(): Promise<Record<string, unknown>>;
+    activity(activityId: string): Promise<Record<string, unknown> | null>;
+    summary(startDate: string, endDate: string): Promise<Record<string, unknown>>;
+    catalog(): DatasetDefinition[];
+}
+/** Converts DuckDB's Date/BigInt values into MCP-safe JSON values. */
+export declare function jsonSafe<T>(value: T): T;

package/dist/core/query/repository.js

@@ -0,0 +1,182 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { sqlString } from './sql.js';
+import { DATASET_CATALOG, getDataset } from './catalog.js';
+export class ReadOnlyRepository {
+    database;
+    paths;
+    constructor(database, paths) {
+        this.database = database;
+        this.paths = paths;
+    }
+    async close() {
+        await this.database.close();
+    }
+    async rows(sql, values) {
+        return this.database.rows(sql, values);
+    }
+    async datasetRelation(datasetName) {
+        const dataset = getDataset(datasetName);
+        if (!dataset.samplesOnly)
+            return dataset.relation;
+        return this.activitySampleRelation();
+    }
+    async activitySampleRelation() {
+        const manifests = await this.rows(`
+      SELECT relative_path
+      FROM stream_manifest
+      QUALIFY row_number() OVER (PARTITION BY provider, activity_source_id ORDER BY content_hash DESC) = 1
+    `);
+        const hasReadableRegisteredStream = manifests.some((manifest) => {
+            const candidate = path.resolve(this.paths.root, manifest.relative_path);
+            const expectedRoot = `${path.resolve(this.paths.lake)}${path.sep}`;
+            return candidate.startsWith(expectedRoot) && candidate.endsWith('.parquet') && existsSync(candidate);
+        });
+        if (hasReadableRegisteredStream) {
+            // A UNION ALL branch for every stream reaches DuckDB's expression-depth
+            // limit around 1,000 activities. The glob is internal and rooted at the
+            // configured lake; the manifest join remains the authoritative allowlist
+            // and supplies stable provider/content-hash provenance.
+            const lakeGlob = path.join(this.paths.lake, '**', '*.parquet');
+            return `
+        SELECT manifest.provider AS provider,
+          manifest.content_hash AS content_hash,
+          sample.activity_source_id,
+          try_cast(sample.timestamp_utc AS TIMESTAMPTZ) AS timestamp_utc,
+          try_cast(sample.elapsed_s AS DOUBLE) AS elapsed_s,
+          try_cast(sample.distance_m AS DOUBLE) AS distance_m,
+          try_cast(sample.latitude AS DOUBLE) AS latitude,
+          try_cast(sample.longitude AS DOUBLE) AS longitude,
+          try_cast(sample.altitude_m AS DOUBLE) AS altitude_m,
+          try_cast(sample.heart_rate_bpm AS DOUBLE) AS heart_rate_bpm,
+          try_cast(sample.power_w AS DOUBLE) AS power_w,
+          try_cast(sample.cadence_rpm AS DOUBLE) AS cadence_rpm,
+          try_cast(sample.speed_mps AS DOUBLE) AS speed_mps,
+          try_cast(sample.temperature_c AS DOUBLE) AS temperature_c,
+          try_cast(sample.grade_pct AS DOUBLE) AS grade_pct,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftRightBalance'), json_extract_string(sample.extras_json, '$.left_right_balance')) AS DOUBLE) AS left_right_balance_pct,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftTorqueEffectiveness'), json_extract_string(sample.extras_json, '$.left_torque_effectiveness')) AS DOUBLE) AS left_torque_effectiveness_pct,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.rightTorqueEffectiveness'), json_extract_string(sample.extras_json, '$.right_torque_effectiveness')) AS DOUBLE) AS right_torque_effectiveness_pct,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftPedalSmoothness'), json_extract_string(sample.extras_json, '$.left_pedal_smoothness')) AS DOUBLE) AS left_pedal_smoothness_pct,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.rightPedalSmoothness'), json_extract_string(sample.extras_json, '$.right_pedal_smoothness')) AS DOUBLE) AS right_pedal_smoothness_pct,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftPowerPhase[0]'), json_extract_string(sample.extras_json, '$.left_power_phase[0]')) AS DOUBLE) AS left_power_phase_start_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftPowerPhase[1]'), json_extract_string(sample.extras_json, '$.left_power_phase[1]')) AS DOUBLE) AS left_power_phase_end_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.rightPowerPhase[0]'), json_extract_string(sample.extras_json, '$.right_power_phase[0]')) AS DOUBLE) AS right_power_phase_start_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.rightPowerPhase[1]'), json_extract_string(sample.extras_json, '$.right_power_phase[1]')) AS DOUBLE) AS right_power_phase_end_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftPowerPhasePeak[0]'), json_extract_string(sample.extras_json, '$.left_power_phase_peak[0]')) AS DOUBLE) AS left_power_phase_peak_start_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftPowerPhasePeak[1]'), json_extract_string(sample.extras_json, '$.left_power_phase_peak[1]')) AS DOUBLE) AS left_power_phase_peak_end_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.rightPowerPhasePeak[0]'), json_extract_string(sample.extras_json, '$.right_power_phase_peak[0]')) AS DOUBLE) AS right_power_phase_peak_start_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.rightPowerPhasePeak[1]'), json_extract_string(sample.extras_json, '$.right_power_phase_peak[1]')) AS DOUBLE) AS right_power_phase_peak_end_deg,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.leftPlatformCenterOffset'), json_extract_string(sample.extras_json, '$.left_pco')) AS DOUBLE) AS left_platform_center_offset_mm,
+          try_cast(coalesce(json_extract_string(sample.extras_json, '$.rightPlatformCenterOffset'), json_extract_string(sample.extras_json, '$.right_pco')) AS DOUBLE) AS right_platform_center_offset_mm,
+          try_cast(sample.extras_json AS JSON) AS extras_json
+        FROM read_parquet(${sqlString(lakeGlob)}, union_by_name = true) AS sample
+        JOIN (
+          SELECT provider, activity_source_id, content_hash
+          FROM stream_manifest
+          QUALIFY row_number() OVER (PARTITION BY provider, activity_source_id ORDER BY content_hash DESC) = 1
+        ) AS manifest USING (activity_source_id)
+      `;
+        }
+        return `SELECT
+      CAST(NULL AS VARCHAR) AS provider,
+      CAST(NULL AS VARCHAR) AS content_hash,
+      CAST(NULL AS VARCHAR) AS activity_source_id,
+      CAST(NULL AS TIMESTAMPTZ) AS timestamp_utc,
+      CAST(NULL AS DOUBLE) AS elapsed_s,
+      CAST(NULL AS DOUBLE) AS distance_m,
+      CAST(NULL AS DOUBLE) AS latitude,
+      CAST(NULL AS DOUBLE) AS longitude,
+      CAST(NULL AS DOUBLE) AS altitude_m,
+      CAST(NULL AS DOUBLE) AS heart_rate_bpm,
+      CAST(NULL AS DOUBLE) AS power_w,
+      CAST(NULL AS DOUBLE) AS cadence_rpm,
+      CAST(NULL AS DOUBLE) AS speed_mps,
+      CAST(NULL AS DOUBLE) AS temperature_c,
+      CAST(NULL AS DOUBLE) AS grade_pct,
+      CAST(NULL AS DOUBLE) AS left_right_balance_pct,
+      CAST(NULL AS DOUBLE) AS left_torque_effectiveness_pct,
+      CAST(NULL AS DOUBLE) AS right_torque_effectiveness_pct,
+      CAST(NULL AS DOUBLE) AS left_pedal_smoothness_pct,
+      CAST(NULL AS DOUBLE) AS right_pedal_smoothness_pct,
+      CAST(NULL AS DOUBLE) AS left_power_phase_start_deg,
+      CAST(NULL AS DOUBLE) AS left_power_phase_end_deg,
+      CAST(NULL AS DOUBLE) AS right_power_phase_start_deg,
+      CAST(NULL AS DOUBLE) AS right_power_phase_end_deg,
+      CAST(NULL AS DOUBLE) AS left_power_phase_peak_start_deg,
+      CAST(NULL AS DOUBLE) AS left_power_phase_peak_end_deg,
+      CAST(NULL AS DOUBLE) AS right_power_phase_peak_start_deg,
+      CAST(NULL AS DOUBLE) AS right_power_phase_peak_end_deg,
+      CAST(NULL AS DOUBLE) AS left_platform_center_offset_mm,
+      CAST(NULL AS DOUBLE) AS right_platform_center_offset_mm,
+      CAST(NULL AS JSON) AS extras_json
+      WHERE FALSE`;
+    }
+    async status() {
+        // @duckdb/node-api shares native statement state on a connection. These
+        // small status reads must remain sequential; concurrent calls can hang a
+        // read-only dashboard request before it writes its response.
+        const runs = await this.rows(`SELECT run_id, provider, cast(from_date AS VARCHAR) AS from_date, cast(started_at AS VARCHAR) AS started_at, cast(completed_at AS VARCHAR) AS completed_at, status, error_count FROM sync_runs ORDER BY started_at DESC LIMIT 20`);
+        const counts = await this.rows(`SELECT
+        (SELECT count(*)::INTEGER FROM activities) AS activities,
+        (SELECT count(*)::INTEGER FROM activity_sources) AS activity_sources,
+        (SELECT count(*)::INTEGER FROM daily_metrics) AS daily_metrics,
+        (SELECT count(*)::INTEGER FROM nutrition_items) AS nutrition_items,
+        (SELECT count(*)::INTEGER FROM source_entities) AS source_entities,
+        (SELECT count(*)::INTEGER FROM retrieval_documents) AS retrieval_documents`);
+        const errors = await this.rows(`SELECT count(*)::INTEGER AS unresolved FROM normalization_errors WHERE resolved_at IS NULL`);
+        const streamCoverage = await this.rows(`SELECT count(*)::INTEGER AS streams, coalesce(sum(row_count), 0)::BIGINT AS sample_rows, min(start_at) AS starts_at, max(end_at) AS ends_at FROM stream_manifest`);
+        const indexState = await this.rows(`SELECT status, mode, source_watermark, cast(built_at AS VARCHAR) AS built_at FROM retrieval_index_state WHERE index_name = 'context'`);
+        const cursors = await this.rows(`SELECT provider, cursor_name, cast(covered_through_date AS VARCHAR) AS covered_through_date, cast(latest_source_date AS VARCHAR) AS latest_source_date, lookback_days, cast(last_completed_at AS VARCHAR) AS last_completed_at, status FROM sync_cursors ORDER BY provider, cursor_name`);
+        return {
+            syncRuns: runs,
+            entityCounts: counts[0] ?? {},
+            unresolvedExtractionErrors: errors[0]?.unresolved ?? 0,
+            streams: streamCoverage[0] ?? { streams: 0, sample_rows: 0 },
+            retrievalIndex: indexState[0] ?? { status: 'stale', mode: 'keyword' },
+            incrementalCursors: cursors,
+        };
+    }
+    async coverage() {
+        const rows = await this.rows(`
+      SELECT 'activities' AS dataset, min(cast(started_at_utc AS DATE)) AS start_date, max(cast(started_at_utc AS DATE)) AS end_date, count(*)::INTEGER AS row_count FROM activities
+      UNION ALL SELECT 'daily_metrics', min(metric_date), max(metric_date), count(*)::INTEGER FROM daily_metrics
+      UNION ALL SELECT 'training_metric_observations', min(cast(observed_at AS DATE)), max(cast(observed_at AS DATE)), count(*)::INTEGER FROM training_metric_observations
+      UNION ALL SELECT 'nutrition_days', min(nutrition_date), max(nutrition_date), count(*)::INTEGER FROM nutrition_days
+      UNION ALL SELECT 'source_entities', min(occurred_on), max(occurred_on), count(*)::INTEGER FROM source_entities
+    `);
+        return { coverage: rows, providers: await this.rows(`SELECT provider, count(*)::INTEGER AS activity_sources FROM activity_sources GROUP BY provider ORDER BY provider`) };
+    }
+    async activity(activityId) {
+        const activity = await this.rows(`SELECT * FROM activities WHERE activity_id = $activityId`, { activityId });
+        if (!activity[0])
+            return null;
+        const sources = await this.rows(`SELECT * FROM activity_sources WHERE activity_id = $activityId ORDER BY CASE provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END, provider`, { activityId });
+        const summaries = await this.rows(`SELECT * FROM activity_summary_facts WHERE activity_id = $activityId ORDER BY CASE provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END, provider`, { activityId });
+        const intervals = await this.rows(`SELECT * FROM activity_interval_facts WHERE activity_id = $activityId ORDER BY CASE provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END, provider, start_s`, { activityId });
+        return { activity: activity[0], sources, summaries, intervals };
+    }
+    async summary(startDate, endDate) {
+        const training = await this.rows(`SELECT cast(started_at_utc AS DATE) AS date, count(*)::INTEGER AS activities, sum(distance_m) AS distance_m, sum(moving_s) AS moving_s, sum(training_load) AS training_load FROM canonical_activity_training WHERE cast(started_at_utc AS DATE) BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE) GROUP BY 1 ORDER BY 1`, { startDate, endDate });
+        const health = await this.rows(`SELECT * FROM daily_health WHERE metric_date BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE) ORDER BY metric_date, provider`, { startDate, endDate });
+        const nutrition = await this.rows(`SELECT * FROM nutrition_days WHERE nutrition_date BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE) ORDER BY nutrition_date, provider`, { startDate, endDate });
+        return { training, health, nutrition };
+    }
+    catalog() {
+        return Object.values(DATASET_CATALOG);
+    }
+}
+/** Converts DuckDB's Date/BigInt values into MCP-safe JSON values. */
+export function jsonSafe(value) {
+    if (typeof value === 'bigint')
+        return String(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map((item) => jsonSafe(item));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, jsonSafe(item)]));
+    }
+    return value;
+}
+//# sourceMappingURL=repository.js.map

package/dist/core/query/sql-guard.d.ts

@@ -0,0 +1,7 @@
+import { ReadOnlyRepository } from './repository.js';
+export declare function queryReadOnlyData(repository: ReadOnlyRepository, request: {
+    sql: string;
+    values?: Record<string, string | number | boolean | null>;
+    cursor?: string;
+    pageSize?: number;
+}): Promise<Record<string, unknown>>;