catence 0.0.0 → 0.1.0

package/dist/core/query/sql-guard.js

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import { DATASET_CATALOG, QueryValidationError } from './catalog.js';
+import { jsonSafe } from './repository.js';
+const forbidden = /\b(attach|detach|copy|export|import|install|load|pragma|set|reset|create|alter|drop|delete|insert|update|merge|vacuum|checkpoint|call|execute|prepare|transaction|begin|commit|rollback|read_parquet|read_csv|read_json|glob|parquet_scan|csv_scan|httpfs|sqlite_scan)\b/i;
+const comments = /(--|\/\*|\*\/)/;
+const MAX_PAGE_SIZE = 500;
+// Leave room for metadata and MCP's envelope instead of constructing a data
+// payload which is just below the database-side limit but still gets cut off
+// by the client transport.
+const MAX_RESPONSE_BYTES = 400_000;
+function queryHash(sql, values) {
+    return createHash('sha256').update(JSON.stringify({ sql, values: Object.fromEntries(Object.entries(values).sort(([left], [right]) => left.localeCompare(right))) })).digest('base64url');
+}
+function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor)).toString('base64url');
+}
+function decodeCursor(cursor, expectedHash) {
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!Number.isInteger(decoded.offset) || decoded.offset < 0 || decoded.hash !== expectedHash)
+            throw new Error();
+        return decoded;
+    }
+    catch {
+        throw new QueryValidationError('Invalid or mismatched cursor. Start the read-only query again.');
+    }
+}
+function safeSql(sql) {
+    const normalized = sql.trim();
+    if (!normalized)
+        throw new QueryValidationError('SQL is required.');
+    if (!/^(select\b|with\b)/i.test(normalized))
+        throw new QueryValidationError('Only a single SELECT or WITH … SELECT statement is allowed.');
+    if (normalized.includes(';') || comments.test(normalized))
+        throw new QueryValidationError('SQL comments and multiple statements are not allowed.');
+    if (forbidden.test(normalized))
+        throw new QueryValidationError('SQL contains a prohibited keyword or filesystem table function.');
+    return normalized;
+}
+function normalizeRelation(name) {
+    // DuckDB's getTableNames() preserves aliases (for example, "activities AS
+    // a"), while the catalog intentionally contains only relation names.
+    // Discard that syntactic alias before doing the allow-list comparison.
+    const relation = name.trim().replace(/\s+(?:as\s+)?(?:"[^"]+"|[A-Za-z_][A-Za-z0-9_]*)\s*$/i, '');
+    return relation.replaceAll('"', '').split('.').at(-1).toLowerCase();
+}
+export async function queryReadOnlyData(repository, request) {
+    const sql = safeSql(request.sql);
+    let relations;
+    try {
+        relations = await repository.database.tableNames(sql);
+    }
+    catch (error) {
+        throw new QueryValidationError(`SQL could not be inspected: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const allowed = new Set(Object.values(DATASET_CATALOG).filter((dataset) => !dataset.samplesOnly && dataset.relation).map((dataset) => dataset.relation.toLowerCase()));
+    for (const relation of relations) {
+        if (!allowed.has(normalizeRelation(relation)))
+            throw new QueryValidationError(`Relation ${relation} is not in the read-only catalog.`);
+    }
+    const ctes = new Set([...sql.matchAll(/(?:\bwith|,)\s*([A-Za-z_][A-Za-z0-9_]*)\s+as\s*\(/gi)].map((match) => match[1].toLowerCase()));
+    for (const match of sql.matchAll(/\b(?:from|join)\s+([A-Za-z_][A-Za-z0-9_.]*)/gi)) {
+        const relation = normalizeRelation(match[1]);
+        if (!allowed.has(relation) && !ctes.has(relation))
+            throw new QueryValidationError(`Relation ${match[1]} is not in the read-only catalog.`);
+    }
+    const values = request.values ?? {};
+    if ('__catence_page_size' in values || '__catence_offset' in values)
+        throw new QueryValidationError('Bind names prefixed with __catence_ are reserved for pagination.');
+    const pageSize = Math.min(Math.max(request.pageSize ?? 100, 1), MAX_PAGE_SIZE);
+    const fingerprint = queryHash(sql, values);
+    const offset = request.cursor ? decodeCursor(request.cursor, fingerprint).offset : 0;
+    const timeout = setTimeout(() => repository.database.interrupt(), 4_000);
+    let totalRows;
+    let rows;
+    try {
+        const total = await repository.rows(`SELECT count(*) AS total_rows FROM (${sql}) AS guarded_query`, values);
+        totalRows = Number(total[0]?.total_rows ?? 0);
+        // ORDER BY ALL creates one stable ordering from every selected column,
+        // including query results without their own ORDER BY. Identical rows are
+        // interchangeable, so paging them cannot omit a distinguishable result.
+        rows = await repository.rows(`SELECT * FROM (${sql}) AS guarded_query ORDER BY ALL LIMIT $__catence_page_size OFFSET $__catence_offset`, { ...values, __catence_page_size: pageSize, __catence_offset: offset });
+    }
+    catch (error) {
+        throw new QueryValidationError(`Read-only query failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    const withinByteLimit = [];
+    let bytes = 0;
+    let oversizedFirstRow = false;
+    for (const row of rows) {
+        const serialized = JSON.stringify(jsonSafe(row));
+        if (bytes + Buffer.byteLength(serialized) > MAX_RESPONSE_BYTES) {
+            oversizedFirstRow = withinByteLimit.length === 0;
+            break;
+        }
+        bytes += Buffer.byteLength(serialized);
+        withinByteLimit.push(row);
+    }
+    const returnedRows = withinByteLimit.length;
+    const truncated = offset + returnedRows < totalRows;
+    const nextCursor = truncated && returnedRows > 0 ? encodeCursor({ hash: fingerprint, offset: offset + returnedRows }) : undefined;
+    return jsonSafe({
+        returnedRows,
+        totalRows,
+        truncated,
+        nextCursor,
+        data: withinByteLimit,
+        provenance: { resolvedViews: relations.map(normalizeRelation), readOnly: true },
+        query: { sql, bindNames: Object.keys(values), pageSize, timeoutMs: 4_000, ordering: 'all selected columns ascending' },
+        caveats: [
+            ...(withinByteLimit.length < rows.length && !oversizedFirstRow ? ['Response reached Catence’s safe response-size limit; continue with nextCursor.'] : []),
+            ...(oversizedFirstRow ? ['The next row alone exceeds Catence’s safe response-size limit. Narrow the selected columns before continuing; no cursor was advanced.'] : []),
+            ...(truncated ? ['Results are incomplete. Do not draw exhaustive conclusions; retrieve remaining pages with nextCursor or narrow the query.'] : []),
+        ],
+        columnTypes: withinByteLimit[0] ? Object.fromEntries(Object.entries(withinByteLimit[0]).map(([key, value]) => [key, value === null ? 'NULL' : typeof value])) : {},
+    });
+}
+//# sourceMappingURL=sql-guard.js.map

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

@@ -0,0 +1,2 @@
+/** Embed an internally-derived literal in a SQL relation expression. */
+export declare function sqlString(value: string): string;

package/dist/core/query/sql.js

@@ -0,0 +1,5 @@
+/** Embed an internally-derived literal in a SQL relation expression. */
+export function sqlString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+//# sourceMappingURL=sql.js.map

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

@@ -0,0 +1,19 @@
+import { ReadOnlyRepository } from './repository.js';
+export type SwimLapsRequest = {
+    /** A source id (for example garmin:123) or a linked logical activity id. */
+    activityId: string;
+    provider?: 'garmin' | 'intervals';
+};
+export type SwimProgressRequest = {
+    startDate?: string;
+    endDate?: string;
+    /** Restrict the comparable pool cohort. Values are metres, not Garmin centimetres. */
+    poolLengthM?: number;
+};
+/** Read-only source-aware swim facts and a deliberately non-physiological progress report. */
+export declare class SwimmingService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    swimLaps(request: SwimLapsRequest): Promise<Record<string, unknown>>;
+    swimProgressReport(request?: SwimProgressRequest): Promise<Record<string, unknown>>;
+}

package/dist/core/query/swimming.js

@@ -0,0 +1,184 @@
+import { QueryValidationError } from './catalog.js';
+function parseJson(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+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;
+}
+/** Read-only source-aware swim facts and a deliberately non-physiological progress report. */
+export class SwimmingService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async swimLaps(request) {
+        const values = { activityId: request.activityId };
+        const providerClause = request.provider ? 'AND source.provider = $provider' : '';
+        if (request.provider)
+            values.provider = request.provider;
+        // A source id can happen to equal its unlinked logical id (for example
+        // garmin:123). Prefer the explicit source interpretation whenever it
+        // exists, otherwise expand a logical id to all of its provider records.
+        const exactSource = await this.repository.rows(`
+      SELECT activity_source_id FROM activity_sources
+      WHERE activity_source_id = $activityId
+      ${request.provider ? 'AND provider = $provider' : ''}
+      LIMIT 1
+    `, values);
+        const identityClause = exactSource.length ? 'source.activity_source_id = $activityId' : 'source.activity_id = $activityId';
+        const sources = await this.repository.rows(`
+      SELECT source.activity_id, source.activity_source_id, source.provider, source.remote_activity_id,
+        cast(activity.started_at_utc AS VARCHAR) AS started_at_utc, activity.sport, activity.name
+      FROM activity_sources AS source
+      JOIN activities AS activity USING (activity_id)
+      WHERE ${identityClause}
+        AND lower(coalesce(activity.sport, '')) LIKE '%swim%'
+        ${providerClause}
+      ORDER BY CASE source.provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END, source.activity_source_id
+    `, values);
+        if (sources.length === 0)
+            throw new QueryValidationError(`No swimming activity source matched ${request.activityId}.`);
+        const data = await Promise.all(sources.map(async (source) => {
+            const [lengths, sets, flags] = await Promise.all([
+                this.repository.rows(`
+          SELECT length_index, lap_index, pool_length_m, cast(start_time AS VARCHAR) AS start_time,
+            duration_s, active_duration_s, distance_m, stroke_count, stroke_rate, swolf,
+            avg_hr, max_hr, is_rest, source, confidence, raw_object_hash
+          FROM swim_length_facts
+          WHERE activity_source_id = $activitySourceId
+          ORDER BY source, length_index
+        `, { activitySourceId: source.activity_source_id }),
+                this.repository.rows(`
+          SELECT source_type, set_index, label, reps, rep_distance_m, total_distance_m,
+            work_s, rest_s, avg_pace, avg_hr, max_hr, stroke_rate, raw_object_hash
+          FROM swim_set_facts
+          WHERE activity_source_id = $activitySourceId
+          ORDER BY source_type, set_index
+        `, { activitySourceId: source.activity_source_id }),
+                this.repository.rows(`
+          SELECT flag_code, severity, details_json, raw_object_hash
+          FROM activity_quality_flag_facts
+          WHERE activity_source_id = $activitySourceId
+          ORDER BY severity DESC, flag_code
+        `, { activitySourceId: source.activity_source_id }),
+            ]);
+            return {
+                ...source,
+                lengths,
+                sets,
+                qualityFlags: flags.map((flag) => ({ ...flag, details_json: parseJson(flag.details_json) })),
+                availability: {
+                    explicitLengthFacts: lengths.length > 0,
+                    setFacts: sets.length > 0,
+                    perLengthPaceAvailable: lengths.some((length) => Number(length.duration_s) > 0 && Number(length.distance_m) > 0),
+                },
+            };
+        }));
+        const noLengthSources = data.filter((source) => !source.availability.explicitLengthFacts).map((source) => source.activity_source_id);
+        return {
+            data,
+            provenance: { relations: ['activities', 'activity_sources', 'swim_length_facts', 'swim_set_facts', 'activity_quality_flag_facts'], idInput: request.activityId },
+            query: request,
+            caveats: [
+                ...(noLengthSources.length ? [`No explicit provider-supplied per-length records are available for: ${noLengthSources.join(', ')}. Catence does not manufacture laps or pace from sample points.`] : []),
+                'Intervals.icu auto blocks and Garmin detected split summaries are returned as sets; neither is silently labelled as a manually pressed lap.',
+            ],
+        };
+    }
+    async swimProgressReport(request = {}) {
+        if (request.poolLengthM !== undefined && (!Number.isFinite(request.poolLengthM) || request.poolLengthM <= 0 || request.poolLengthM > 200)) {
+            throw new QueryValidationError('poolLengthM must be a positive value no greater than 200 metres.');
+        }
+        const values = {};
+        const poolLengthSql = `CASE
+      WHEN try_cast(json_extract_string(summary.metrics_json, '$.poolLength') AS DOUBLE) >= 100
+        THEN try_cast(json_extract_string(summary.metrics_json, '$.poolLength') AS DOUBLE) / 100
+      ELSE try_cast(json_extract_string(summary.metrics_json, '$.poolLength') AS DOUBLE)
+    END`;
+        const clauses = ["source.provider = 'garmin'", "lower(coalesce(activity.sport, '')) LIKE '%swim%'", ...addDateRange('activity.started_at_utc', request, values)];
+        if (request.poolLengthM !== undefined) {
+            values.poolLengthM = request.poolLengthM;
+            clauses.push(`abs((${poolLengthSql}) - $poolLengthM) <= 0.01`);
+        }
+        const rows = await this.repository.rows(`
+      WITH quality AS (
+        SELECT activity_source_id,
+          json_group_array(json_object('code', flag_code, 'severity', severity, 'details', details_json)) AS quality_flags
+        FROM activity_quality_flags GROUP BY activity_source_id
+      ), lengths AS (
+        SELECT activity_source_id, count(*) AS length_fact_count,
+          count(*) FILTER (WHERE duration_s > 0 AND distance_m > 0) AS pace_length_fact_count
+        FROM swim_lengths GROUP BY activity_source_id
+      ), sets AS (
+        SELECT activity_source_id, count(*) AS set_fact_count FROM swim_sets GROUP BY activity_source_id
+      )
+      SELECT source.activity_id, source.activity_source_id, cast(activity.started_at_utc AS VARCHAR) AS started_at_utc,
+        activity.sport, activity.name, summary.distance_m, summary.moving_s, summary.elapsed_s, summary.avg_hr, summary.max_hr,
+        ${poolLengthSql} AS pool_length_m,
+        try_cast(json_extract_string(summary.metrics_json, '$.activeLengths') AS DOUBLE) AS active_lengths,
+        try_cast(json_extract_string(summary.metrics_json, '$.averageSwolf') AS DOUBLE) AS average_swolf,
+        try_cast(json_extract_string(summary.metrics_json, '$.fastestSplit_100') AS DOUBLE) AS fastest_100_s,
+        try_cast(json_extract_string(summary.metrics_json, '$.averageSwimCadenceInStrokesPerMinute') AS DOUBLE) AS stroke_cadence_spm,
+        coalesce(lengths.length_fact_count, 0) AS length_fact_count,
+        coalesce(lengths.pace_length_fact_count, 0) AS pace_length_fact_count,
+        coalesce(sets.set_fact_count, 0) AS set_fact_count,
+        coalesce(quality.quality_flags, cast('[]' AS JSON)) AS quality_flags
+      FROM activity_sources AS source
+      JOIN activities AS activity USING (activity_id)
+      JOIN activity_summaries AS summary USING (activity_source_id)
+      LEFT JOIN lengths USING (activity_source_id)
+      LEFT JOIN sets USING (activity_source_id)
+      LEFT JOIN quality USING (activity_source_id)
+      WHERE ${clauses.join(' AND ')}
+      ORDER BY activity.started_at_utc ASC, source.activity_source_id ASC
+    `, values);
+        const sessions = rows.map((row) => ({
+            ...row,
+            length_fact_count: Number(row.length_fact_count),
+            pace_length_fact_count: Number(row.pace_length_fact_count),
+            set_fact_count: Number(row.set_fact_count),
+            quality_flags: parseJson(row.quality_flags),
+            dataCompleteness: {
+                explicitLengthFactsAvailable: Number(row.length_fact_count) > 0,
+                setFactsAvailable: Number(row.set_fact_count) > 0,
+                perLengthPaceAvailable: Number(row.pace_length_fact_count) > 0,
+            },
+        }));
+        return {
+            data: {
+                sessions,
+                coverage: {
+                    sessionCount: sessions.length,
+                    poolSessionCount: sessions.filter((session) => session.pool_length_m !== null).length,
+                    explicitLengthFactSessions: sessions.filter((session) => session.length_fact_count > 0).length,
+                    setFactSessions: sessions.filter((session) => session.set_fact_count > 0).length,
+                },
+            },
+            provenance: { relations: ['activities', 'activity_sources', 'activity_summaries', 'swim_lengths', 'swim_sets', 'activity_quality_flags'], summaryProvider: 'garmin' },
+            query: request,
+            caveats: [
+                'This report compares Garmin-native summary metrics. It does not infer a pool pace curve from moving time divided by distance.',
+                'Per-length pace, rest, and HR drift are reported only when explicit swim-length records exist; activity samples never create synthetic lengths.',
+                'Intervals.icu auto blocks are separately available through get_swim_laps and retain source_type: intervals_auto.',
+                ...(sessions.length === 0 ? ['No Garmin swimming sessions matched the selected range and pool length.'] : []),
+            ],
+        };
+    }
+}
+//# sourceMappingURL=swimming.js.map

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

@@ -0,0 +1,45 @@
+import { type ReadOnlyRepository } 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 declare const WELLNESS_METRICS: readonly ["resting_hr_bpm", "hrv_ms", "sleep_seconds", "sleep_score", "stress", "body_battery", "readiness", "spo2_pct", "steps", "training_load", "activity_count", "distance_m", "moving_s"];
+export type WellnessMetric = (typeof WELLNESS_METRICS)[number];
+export type WellnessCorrelationRequest = {
+    metricA: WellnessMetric;
+    metricB: WellnessMetric;
+    startDate?: string;
+    endDate?: string;
+    method?: 'pearson' | 'spearman';
+    lagDays?: number;
+    scanLags?: boolean;
+};
+export type WellnessBaselineRequest = {
+    metrics?: WellnessMetric[];
+    endDate?: string;
+    windowDays?: number;
+};
+export type WellnessAnomalyRequest = {
+    metrics?: WellnessMetric[];
+    startDate?: string;
+    endDate?: string;
+    zThreshold?: number;
+};
+export type WellnessCoverageRequest = {
+    metrics?: WellnessMetric[];
+    startDate?: string;
+    endDate?: string;
+};
+export declare class WellnessService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    correlate(request: WellnessCorrelationRequest): Promise<Record<string, unknown>>;
+    baselines(request: WellnessBaselineRequest): Promise<Record<string, unknown>>;
+    anomalies(request: WellnessAnomalyRequest): Promise<Record<string, unknown>>;
+    coverage(request: WellnessCoverageRequest): Promise<Record<string, unknown>>;
+    private assertMetric;
+    private resolveRange;
+    private dailyRows;
+    private correlation;
+}