catence 0.0.0 → 0.1.0

package/dist/core/query/analytics.js

@@ -0,0 +1,395 @@
+import { createHash } from 'node:crypto';
+import { getColumn, getDataset, QueryValidationError } from './catalog.js';
+import { jsonSafe } from './repository.js';
+const resolutionIntervals = {
+    '1m': 'minute', '5m': 'minute', '15m': 'minute', '1h': 'hour', day: 'day', week: 'week',
+};
+function quoteIdentifier(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}
+function valuesRecord(values, key, value) {
+    values[key] = value;
+}
+function compileFilter(dataset, filter, index, values) {
+    const column = getColumn(dataset, filter.column);
+    if (!column.filterable)
+        throw new QueryValidationError(`${filter.column} cannot be used as a filter on ${dataset.name}.`);
+    const sqlColumn = quoteIdentifier(column.name);
+    const key = `filter${index}`;
+    if (filter.op === 'eq' || filter.op === 'neq') {
+        if (filter.value === null)
+            return `${sqlColumn} IS ${filter.op === 'eq' ? '' : 'NOT '}NULL`;
+        valuesRecord(values, key, filter.value);
+        return `${sqlColumn} ${filter.op === 'eq' ? '=' : '<>'} $${key}`;
+    }
+    if (filter.op === 'gt' || filter.op === 'gte' || filter.op === 'lt' || filter.op === 'lte') {
+        valuesRecord(values, key, filter.value);
+        return `${sqlColumn} ${{ gt: '>', gte: '>=', lt: '<', lte: '<=' }[filter.op]} $${key}`;
+    }
+    if (filter.op === 'contains') {
+        if (typeof filter.value !== 'string')
+            throw new QueryValidationError('contains filters require a string value.');
+        valuesRecord(values, key, filter.value);
+        return `${sqlColumn} ILIKE '%' || $${key} || '%'`;
+    }
+    if (filter.op === 'in') {
+        if (!Array.isArray(filter.value) || filter.value.length === 0 || filter.value.length > 100)
+            throw new QueryValidationError('in filters require 1–100 values.');
+        const placeholders = filter.value.map((item, itemIndex) => {
+            const itemKey = `${key}_${itemIndex}`;
+            valuesRecord(values, itemKey, item);
+            return `$${itemKey}`;
+        });
+        return `${sqlColumn} IN (${placeholders.join(', ')})`;
+    }
+    if (filter.op === 'between') {
+        if (!Array.isArray(filter.value) || filter.value.length !== 2)
+            throw new QueryValidationError('between filters require exactly two values.');
+        valuesRecord(values, `${key}_start`, filter.value[0]);
+        valuesRecord(values, `${key}_end`, filter.value[1]);
+        return `${sqlColumn} BETWEEN $${key}_start AND $${key}_end`;
+    }
+    throw new QueryValidationError(`Unsupported filter operator: ${filter.op}`);
+}
+export function compileFilters(dataset, filters = [], startDate, endDate, activityId) {
+    const values = {};
+    const clauses = filters.map((filter, index) => compileFilter(dataset, filter, index, values));
+    if ((startDate || endDate) && !dataset.dateColumn)
+        throw new QueryValidationError(`${dataset.name} has no date column; scope it using an ID filter.`);
+    if (startDate) {
+        values.startDate = startDate;
+        clauses.push(`${quoteIdentifier(dataset.dateColumn)} >= cast($startDate AS ${dataset.dateColumn === 'metric_date' || dataset.dateColumn === 'nutrition_date' || dataset.dateColumn === 'occurred_on' ? 'DATE' : 'TIMESTAMPTZ'})`);
+    }
+    if (endDate) {
+        values.endDate = dataset.dateColumn === 'metric_date' || dataset.dateColumn === 'nutrition_date' || dataset.dateColumn === 'occurred_on' ? endDate : `${endDate}T23:59:59.999Z`;
+        clauses.push(`${quoteIdentifier(dataset.dateColumn)} <= cast($endDate AS ${dataset.dateColumn === 'metric_date' || dataset.dateColumn === 'nutrition_date' || dataset.dateColumn === 'occurred_on' ? 'DATE' : 'TIMESTAMPTZ'})`);
+    }
+    if (activityId) {
+        const activityColumn = dataset.columns.find((column) => column.name === 'activity_id');
+        if (!activityColumn)
+            throw new QueryValidationError(`${dataset.name} cannot be scoped by logical activity ID.`);
+        values.activityId = activityId;
+        clauses.push('"activity_id" = $activityId');
+    }
+    return { where: clauses.length ? `WHERE ${clauses.join(' AND ')}` : '', values };
+}
+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 || !decoded.resolution)
+            throw new Error();
+        return decoded;
+    }
+    catch {
+        throw new QueryValidationError('Invalid or mismatched cursor. Start the series query again.');
+    }
+}
+function queryHash(request) {
+    return createHash('sha256').update(JSON.stringify(request)).digest('base64url');
+}
+function isNumeric(column) {
+    return column.metric === true;
+}
+function isTemporal(column) {
+    return /(?:^|\s)(?:DATE|TIME|TIMESTAMP)/i.test(column.type);
+}
+function timestampExpression(dataset) {
+    if (!dataset.dateColumn)
+        throw new QueryValidationError(`${dataset.name} has no time axis.`);
+    return quoteIdentifier(dataset.dateColumn);
+}
+function bucketExpression(timestamp, resolution) {
+    if (resolution === 'day' || resolution === 'week' || resolution === '1h')
+        return `date_trunc('${resolutionIntervals[resolution]}', ${timestamp})`;
+    if (resolution === '1m')
+        return `date_trunc('minute', ${timestamp})`;
+    if (resolution === '5m' || resolution === '15m') {
+        const seconds = resolution === '5m' ? 300 : 900;
+        return `to_timestamp(floor(epoch(${timestamp}) / ${seconds}) * ${seconds})`;
+    }
+    throw new QueryValidationError(`Cannot bucket with ${resolution}.`);
+}
+function sourceRelation(relation) {
+    return relation.trimStart().toLowerCase().startsWith('select') ? `(${relation})` : quoteIdentifier(relation);
+}
+export class AnalyticsService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async readSeries(request) {
+        const dataset = getDataset(request.dataset);
+        const metrics = [...new Set(request.metrics)];
+        if (metrics.length === 0 || metrics.length > 12)
+            throw new QueryValidationError('read_series requires 1–12 metrics.');
+        for (const metric of metrics) {
+            const column = getColumn(dataset, metric);
+            if (!isNumeric(column))
+                throw new QueryValidationError(`${metric} is not a numeric metric in ${dataset.name}.`);
+        }
+        const requestedResolution = request.resolution ?? 'auto';
+        // MCP validates a 1,000-point public page. Internal model fitting can use
+        // the documented 5,000-point cap without changing the public tool limit.
+        const pageSize = Math.min(Math.max(request.pageSize ?? 1_000, 1), 5_000);
+        const { cursor: ignoredCursor, pageSize: ignoredPageSize, ...fingerprintRequest } = request;
+        void ignoredCursor;
+        void ignoredPageSize;
+        const fingerprint = queryHash(fingerprintRequest);
+        const cursor = request.cursor ? decodeCursor(request.cursor, fingerprint) : undefined;
+        let resolution = cursor?.resolution ?? requestedResolution;
+        const relation = await this.repository.datasetRelation(dataset.name);
+        const source = sourceRelation(relation);
+        const { where, values } = compileFilters(dataset, request.filters, request.startDate, request.endDate, request.activityId);
+        if (dataset.name === 'activity_samples' && !request.startDate && !request.endDate && !request.activityId && !request.filters?.some((filter) => filter.column === 'activity_source_id')) {
+            throw new QueryValidationError('activity_samples requires a date scope or activity_source_id filter.');
+        }
+        const date = timestampExpression(dataset);
+        const rawSelect = `${date} AS timestamp, ${metrics.map(quoteIdentifier).join(', ')}, ${dataset.provenanceColumns.filter((column) => dataset.columns.some((known) => known.name === column)).map(quoteIdentifier).join(', ')}`;
+        const order = `${date} ASC, ${dataset.provenanceColumns[0] ? quoteIdentifier(dataset.provenanceColumns[0]) : '1'} ASC`;
+        let rawTotalRows;
+        if (resolution === 'auto') {
+            const probe = await this.repository.rows(`SELECT count(*)::BIGINT AS row_count FROM ${source} AS source ${where}`, values);
+            const rowCount = Number(probe[0]?.row_count ?? 0);
+            rawTotalRows = rowCount;
+            resolution = rowCount > pageSize
+                ? dataset.name === 'activity_samples' ? '1m'
+                    : ['daily_metrics', 'daily_health', 'nutrition_days', 'nutrition_items'].includes(dataset.name) ? 'week'
+                        : 'day'
+                : 'raw';
+        }
+        const offset = cursor?.offset ?? 0;
+        let totalRows;
+        if (resolution === 'raw') {
+            if (rawTotalRows === undefined) {
+                const total = await this.repository.rows(`SELECT count(*) AS total_rows FROM ${source} AS source ${where}`, values);
+                rawTotalRows = Number(total[0]?.total_rows ?? 0);
+            }
+            totalRows = rawTotalRows;
+        }
+        else {
+            const bucket = bucketExpression(date, resolution);
+            const provenance = dataset.provenanceColumns.filter((column) => dataset.columns.some((known) => known.name === column));
+            const total = await this.repository.rows(`
+        SELECT count(*) AS total_rows FROM (
+          SELECT ${bucket} AS timestamp
+          FROM ${source} AS source ${where}
+          GROUP BY ${bucket}, ${provenance.map(quoteIdentifier).join(', ')}
+        ) AS series_total
+      `, values);
+            totalRows = Number(total[0]?.total_rows ?? 0);
+        }
+        values.limit = pageSize + 1;
+        values.offset = offset;
+        let rows;
+        if (resolution === 'raw') {
+            rows = await this.repository.rows(`SELECT ${rawSelect} FROM ${source} AS source ${where} ORDER BY ${order} LIMIT $limit OFFSET $offset`, values);
+        }
+        else {
+            const bucket = bucketExpression(date, resolution);
+            const provenance = dataset.provenanceColumns.filter((column) => dataset.columns.some((known) => known.name === column));
+            rows = await this.repository.rows(`
+        SELECT ${bucket} AS timestamp, ${metrics.map((metric) => `avg(${quoteIdentifier(metric)}) AS ${quoteIdentifier(metric)}`).join(', ')}, ${provenance.map(quoteIdentifier).join(', ')}
+        FROM ${source} AS source ${where}
+        GROUP BY ${bucket}, ${provenance.map(quoteIdentifier).join(', ')}
+        ORDER BY timestamp ASC${provenance.length ? `, ${provenance.map(quoteIdentifier).join(', ')}` : ''}
+        LIMIT $limit OFFSET $offset
+      `, values);
+        }
+        const hasMore = rows.length > pageSize;
+        if (hasMore)
+            rows.pop();
+        const returnedRows = rows.length;
+        const truncated = offset + returnedRows < totalRows;
+        return jsonSafe({
+            returnedRows,
+            totalRows,
+            truncated,
+            nextCursor: truncated ? encodeCursor({ hash: fingerprint, offset: offset + returnedRows, resolution }) : undefined,
+            data: rows,
+            provenance: { dataset: dataset.name, source: dataset.relation ?? 'registered stream_manifest Parquet only', columns: dataset.provenanceColumns },
+            query: { dataset: dataset.name, metrics, filters: request.filters ?? [], startDate: request.startDate, endDate: request.endDate, activityId: request.activityId, requestedResolution, resolution, pageSize },
+            caveats: [
+                ...(resolution !== requestedResolution && requestedResolution === 'auto' ? ['Automatically downsampled to stay within the first response page. Use the returned cursor for later pages.'] : []),
+                ...(truncated ? ['Results are incomplete. Do not draw exhaustive conclusions; retrieve remaining pages with nextCursor or narrow the query.'] : []),
+            ],
+        });
+    }
+    async aggregate(request) {
+        const dataset = getDataset(request.dataset);
+        if (dataset.samplesOnly && !request.filters?.some((filter) => filter.column === 'activity_source_id'))
+            throw new QueryValidationError('activity_samples aggregation requires an activity_source_id filter.');
+        if (request.metrics.length === 0 || request.metrics.length > 12)
+            throw new QueryValidationError('aggregate_data requires 1–12 aggregations.');
+        const relation = await this.repository.datasetRelation(dataset.name);
+        const source = sourceRelation(relation);
+        const { where, values } = compileFilters(dataset, request.filters, request.startDate, request.endDate);
+        const dimensions = [...new Set(request.dimensions ?? [])];
+        for (const dimension of dimensions) {
+            const column = getColumn(dataset, dimension);
+            if (!column.groupable)
+                throw new QueryValidationError(`${dimension} is not a permitted grouping.`);
+        }
+        const groups = dimensions.map(quoteIdentifier);
+        const selections = [...groups];
+        if (request.timeBucket) {
+            if (!dataset.dateColumn)
+                throw new QueryValidationError(`${dataset.name} cannot be time-bucketed.`);
+            const bucket = `date_trunc('${request.timeBucket}', ${timestampExpression(dataset)})`;
+            selections.unshift(`${bucket} AS time_bucket`);
+            groups.unshift(bucket);
+        }
+        for (const [index, metric] of request.metrics.entries()) {
+            const column = getColumn(dataset, metric.column);
+            // A timestamp has no meaningful sum/mean/percentile, but its extrema are
+            // both safe and useful (for example, first/last observation dates).
+            if (metric.operation !== 'count' && !isNumeric(column) && !((metric.operation === 'min' || metric.operation === 'max') && isTemporal(column))) {
+                throw new QueryValidationError(`${metric.column} is not numeric; only min and max support temporal columns.`);
+            }
+            const outputName = metric.as ?? `${metric.operation}_${metric.column}`;
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(outputName))
+                throw new QueryValidationError('Aggregation aliases must be simple identifiers.');
+            if (metric.operation === 'percentile') {
+                const percentile = metric.percentile ?? 0.5;
+                if (!(percentile > 0 && percentile < 1))
+                    throw new QueryValidationError('percentile must be between 0 and 1.');
+                values[`percentile${index}`] = percentile;
+                selections.push(`quantile_cont(${quoteIdentifier(metric.column)}, $percentile${index}) AS ${quoteIdentifier(outputName)}`);
+            }
+            else if (metric.operation === 'count')
+                selections.push(`count(${quoteIdentifier(metric.column)}) AS ${quoteIdentifier(outputName)}`);
+            else
+                selections.push(`${{ sum: 'sum', mean: 'avg', min: 'min', max: 'max' }[metric.operation]}(${quoteIdentifier(metric.column)}) AS ${quoteIdentifier(outputName)}`);
+        }
+        // ``timeBucket`` produces the public ``time_bucket`` field. Keep ``bucket``
+        // as an ordering-only compatibility alias for calls made before that name
+        // was standardized.
+        const requestedOrderBy = request.orderBy?.column;
+        const orderBy = requestedOrderBy === 'bucket' && request.timeBucket ? 'time_bucket' : requestedOrderBy;
+        const aliases = selections.map((selection) => selection.match(/AS "?([A-Za-z_][A-Za-z0-9_]*)"?$/i)?.[1]).filter(Boolean);
+        if (orderBy && !aliases.includes(orderBy) && !dimensions.includes(orderBy))
+            throw new QueryValidationError('orderBy must name a selected dimension, time_bucket, or aggregation alias.');
+        values.limit = Math.min(Math.max(request.limit ?? 100, 1), 500);
+        const rows = await this.repository.rows(`SELECT ${selections.join(', ')} FROM ${source} AS source ${where}${groups.length ? ` GROUP BY ${groups.join(', ')}` : ''}${orderBy ? ` ORDER BY ${quoteIdentifier(orderBy)} ${request.orderBy?.direction === 'asc' ? 'ASC' : 'DESC'}` : ''} LIMIT $limit`, values);
+        return jsonSafe({ data: rows, provenance: { dataset: dataset.name, columns: dataset.provenanceColumns }, query: request, caveats: [] });
+    }
+    async analyzeSeries(request) {
+        const compareMetric = request.compareMetric ?? request.metrics[1];
+        const series = await this.readSeries({ ...request, metrics: [...new Set([request.metrics[0], ...(compareMetric ? [compareMetric] : [])])], resolution: request.resolution ?? 'auto', pageSize: 1_000 });
+        const rows = series.data;
+        const primary = request.metrics[0];
+        const values = rows.map((row) => numberOrNull(row[primary]));
+        const finite = values.filter((value) => value !== null);
+        if (finite.length < 3)
+            throw new QueryValidationError('At least three non-null observations are required for analysis.');
+        const analysis = request.analysis;
+        let result;
+        if (analysis === 'rolling_mean' || analysis === 'rolling_median') {
+            const window = Math.min(Math.max(request.window ?? 7, 2), 100);
+            result = { window, values: rolling(values, window, analysis === 'rolling_mean' ? mean : median) };
+        }
+        else if (analysis === 'baseline_change') {
+            const baseline = mean(finite.slice(0, Math.max(1, Math.floor(finite.length / 3))));
+            const recent = mean(finite.slice(-Math.max(1, Math.floor(finite.length / 3))));
+            result = { baseline, recent, absoluteChange: recent - baseline, percentChange: baseline === 0 ? null : ((recent - baseline) / Math.abs(baseline)) * 100 };
+        }
+        else if (analysis === 'z_score') {
+            const center = mean(finite);
+            const deviation = standardDeviation(finite);
+            result = { mean: center, standardDeviation: deviation, values: values.map((value) => value === null || deviation === 0 ? null : (value - center) / deviation) };
+        }
+        else if (analysis === 'pearson' || analysis === 'spearman') {
+            const compare = compareMetric;
+            if (!compare)
+                throw new QueryValidationError('Correlation requires compareMetric or a second metric.');
+            const pairs = rows.map((row) => [numberOrNull(row[primary]), numberOrNull(row[compare])]).filter((pair) => pair[0] !== null && pair[1] !== null);
+            if (pairs.length < 3)
+                throw new QueryValidationError('At least three paired values are required for correlation.');
+            const [x, y] = pairs.reduce((accumulator, pair) => { accumulator[0].push(pair[0]); accumulator[1].push(pair[1]); return accumulator; }, [[], []]);
+            result = { compareMetric: compare, correlation: pearson(analysis === 'spearman' ? ranks(x) : x, analysis === 'spearman' ? ranks(y) : y), pairedCount: pairs.length, method: analysis };
+        }
+        else if (analysis === 'seasonal_comparison') {
+            const byMonth = new Map();
+            rows.forEach((row, index) => {
+                if (values[index] === null || !row.timestamp)
+                    return;
+                const month = timestampText(row.timestamp).slice(5, 7);
+                byMonth.set(month, [...(byMonth.get(month) ?? []), values[index]]);
+            });
+            result = { monthlyMeans: Object.fromEntries([...byMonth.entries()].map(([month, seriesValues]) => [month, mean(seriesValues)])) };
+        }
+        else {
+            const x = rows.map((_, index) => index).filter((index) => values[index] !== null);
+            const y = values.filter((value) => value !== null);
+            result = analysis === 'linear_trend' ? linearFit(x, y) : theilSen(x, y);
+        }
+        return jsonSafe({ data: result, provenance: series.provenance, query: { ...series.query, analysis }, caveats: [rows.length >= 1_000 && series.nextCursor ? 'Analysis used the first 1,000 page points; choose a coarser resolution or narrower scope for a complete analysis.' : 'Null metric values were excluded from calculations.'], input: { returnedRows: rows.length, nonNullValues: finite.length, dateCoverage: coverage(rows) } });
+    }
+    async fitSeriesModel(request) {
+        const yMetric = request.yMetric ?? request.metrics[0];
+        if (!yMetric)
+            throw new QueryValidationError('A y metric is required.');
+        const series = await this.readSeries({ ...request, metrics: [...new Set([yMetric, ...(request.xMetric ? [request.xMetric] : [])])], pageSize: 5_000 });
+        const rows = series.data;
+        if (rows.length > 5_000)
+            throw new QueryValidationError('Model input exceeds the 5,000-point cap. Use a coarser resolution or narrower range.');
+        const pairs = rows.map((row, index) => [request.xMetric ? numberOrNull(row[request.xMetric]) : index, numberOrNull(row[yMetric])]).filter((pair) => pair[0] !== null && pair[1] !== null);
+        if (pairs.length < (request.model === 'polynomial_3' ? 6 : 3))
+            throw new QueryValidationError('Insufficient non-null input for the selected model.');
+        const x = pairs.map((pair) => pair[0]);
+        const y = pairs.map((pair) => pair[1]);
+        if (new Set(x).size < 2 || new Set(y).size < 2)
+            throw new QueryValidationError('Model input cannot be constant.');
+        const fit = request.model === 'ols_linear' ? linearFit(x, y) : request.model === 'theil_sen_linear' ? theilSen(x, y) : polynomialFit(x, y, request.model === 'polynomial_2' ? 2 : 3);
+        const predictions = x.map((item) => predict(fit.coefficients, item));
+        const residuals = y.map((item, index) => item - predictions[index]);
+        return jsonSafe({ data: { model: request.model, xMetric: request.xMetric ?? 'observation_index', yMetric, coefficients: fit.coefficients, rSquared: rSquared(y, predictions), residuals: { mean: mean(residuals), standardDeviation: standardDeviation(residuals), min: Math.min(...residuals), max: Math.max(...residuals) } }, provenance: series.provenance, query: series.query, caveats: ['Descriptive fit only; it is not a physiological or sport-performance model.', 'Rows with null x or y values were excluded.', ...(series.nextCursor ? ['Input was capped at the first 5,000 points after the declared resolution.'] : [])], input: { selectedRows: rows.length, fittedRows: pairs.length, excludedRows: rows.length - pairs.length, cappedRows: series.nextCursor ? 'at least 1 additional page' : 0, dateCoverage: coverage(rows) } });
+    }
+}
+function numberOrNull(value) { return typeof value === 'number' && Number.isFinite(value) ? value : null; }
+function timestampText(value) { return value instanceof Date ? value.toISOString() : String(value); }
+function mean(values) { return values.reduce((sum, value) => sum + value, 0) / values.length; }
+function median(values) { const sorted = [...values].sort((a, b) => a - b); const middle = Math.floor(sorted.length / 2); return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2; }
+function standardDeviation(values) { const center = mean(values); return Math.sqrt(values.reduce((sum, value) => sum + (value - center) ** 2, 0) / values.length); }
+function rolling(values, window, fn) { return values.map((_, index) => { const chunk = values.slice(Math.max(0, index - window + 1), index + 1).filter((item) => item !== null); return chunk.length ? fn(chunk) : null; }); }
+function pearson(x, y) { const sx = standardDeviation(x); const sy = standardDeviation(y); if (sx === 0 || sy === 0)
+    return null; const mx = mean(x); const my = mean(y); return x.reduce((sum, value, index) => sum + (value - mx) * (y[index] - my), 0) / (x.length * sx * sy); }
+function ranks(values) { const ordered = values.map((value, index) => ({ value, index })).sort((a, b) => a.value - b.value); const output = 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++)
+        output[ordered[cursor].index] = rank;
+    index = end + 1;
+} return output; }
+function linearFit(x, y) { const mx = mean(x); const my = mean(y); const denominator = x.reduce((sum, value) => sum + (value - mx) ** 2, 0); if (denominator === 0)
+    throw new QueryValidationError('x values are constant.'); const slope = x.reduce((sum, value, index) => sum + (value - mx) * (y[index] - my), 0) / denominator; const intercept = my - slope * mx; return { coefficients: [intercept, slope], slope, intercept }; }
+function theilSen(x, y) { const slopes = []; for (let left = 0; left < x.length; left++)
+    for (let right = left + 1; right < x.length; right++)
+        if (x[right] !== x[left])
+            slopes.push((y[right] - y[left]) / (x[right] - x[left])); const slope = median(slopes); const intercept = median(x.map((value, index) => y[index] - slope * value)); return { coefficients: [intercept, slope], slope, intercept }; }
+function polynomialFit(x, y, degree) { const size = degree + 1; const matrix = Array.from({ length: size }, (_, row) => Array.from({ length: size + 1 }, (_, column) => column === size ? x.reduce((sum, value, index) => sum + y[index] * value ** row, 0) : x.reduce((sum, value) => sum + value ** (row + column), 0))); for (let pivot = 0; pivot < size; pivot++) {
+    let best = pivot;
+    for (let row = pivot + 1; row < size; row++)
+        if (Math.abs(matrix[row][pivot]) > Math.abs(matrix[best][pivot]))
+            best = row;
+    [matrix[pivot], matrix[best]] = [matrix[best], matrix[pivot]];
+    if (Math.abs(matrix[pivot][pivot]) < 1e-12)
+        throw new QueryValidationError('Polynomial fit is singular.');
+    const scale = matrix[pivot][pivot];
+    for (let column = pivot; column <= size; column++)
+        matrix[pivot][column] /= scale;
+    for (let row = 0; row < size; row++)
+        if (row !== pivot) {
+            const factor = matrix[row][pivot];
+            for (let column = pivot; column <= size; column++)
+                matrix[row][column] -= factor * matrix[pivot][column];
+        }
+} return { coefficients: matrix.map((row) => row[size]) }; }
+function predict(coefficients, x) { return coefficients.reduce((sum, coefficient, index) => sum + coefficient * x ** index, 0); }
+function rSquared(actual, predicted) { const total = actual.reduce((sum, value) => sum + (value - mean(actual)) ** 2, 0); return total === 0 ? null : 1 - actual.reduce((sum, value, index) => sum + (value - predicted[index]) ** 2, 0) / total; }
+function coverage(rows) { return { start: rows[0]?.timestamp ?? null, end: rows.at(-1)?.timestamp ?? null }; }
+//# sourceMappingURL=analytics.js.map

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

@@ -0,0 +1,26 @@
+export type DatasetName = 'activities' | 'canonical_activities' | 'canonical_activity_facts' | 'activity_sources' | 'activity_summaries' | 'activity_intervals' | 'swim_lengths' | 'swim_sets' | 'activity_quality_flags' | 'daily_metrics' | 'daily_health' | 'training_metrics' | 'training_metric_observations' | 'wellness_samples' | 'health_sessions' | 'power_bests' | 'nutrition_days' | 'nutrition_items' | 'events' | 'workouts' | 'workout_documents' | 'training_plans' | 'routes' | 'gear' | 'devices' | 'goals' | 'achievements' | 'messages' | 'source_entities' | 'activity_samples' | 'activity_links' | 'activity_segments' | 'segments' | 'segment_effort_history' | 'strava_gear';
+export type CatalogColumn = {
+    name: string;
+    type: string;
+    unit?: string;
+    description?: string;
+    filterable?: boolean;
+    groupable?: boolean;
+    metric?: boolean;
+};
+export type DatasetDefinition = {
+    name: DatasetName;
+    relation?: string;
+    description: string;
+    dateColumn?: string;
+    provenanceColumns: string[];
+    columns: CatalogColumn[];
+    permittedGroupings: string[];
+    samplesOnly?: boolean;
+};
+export declare const DATASET_CATALOG: Record<Exclude<DatasetName, 'training_metrics'>, DatasetDefinition>;
+export declare function getDataset(name: string): DatasetDefinition;
+export declare function getColumn(dataset: DatasetDefinition, name: string): CatalogColumn;
+export declare class QueryValidationError extends Error {
+    constructor(message: string);
+}

package/dist/core/query/catalog.js

@@ -0,0 +1,141 @@
+const column = (name, type, options = {}) => ({ name, type, ...options });
+export const DATASET_CATALOG = {
+    activities: {
+        name: 'activities', relation: 'activities', description: 'Logical activities linked by provider IDs, unique high-confidence fuzzy evidence, or an explicit manual correction.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_id', 'link_state'], permittedGroupings: ['sport', 'link_state'],
+        columns: [column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('started_at_local', 'VARCHAR'), column('timezone', 'VARCHAR'), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR', { filterable: true }), column('link_state', 'VARCHAR', { filterable: true, groupable: true })],
+    },
+    canonical_activities: {
+        name: 'canonical_activities', relation: 'canonical_activity_training', description: 'One training interpretation per linked activity; Garmin is canonical when present, while Intervals analysis values remain separately provenance-tagged.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_id', 'activity_source_id', 'provider'], permittedGroupings: ['provider', 'sport'],
+        columns: [column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR'), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('calories', 'DOUBLE', { unit: 'kcal', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('weighted_power', 'DOUBLE', { unit: 'W', metric: true }), column('training_load', 'DOUBLE', { metric: true }), column('rpe', 'DOUBLE', { metric: true }), column('feel', 'DOUBLE', { metric: true })],
+    },
+    canonical_activity_facts: {
+        name: 'canonical_activity_facts', relation: 'canonical_activity_facts', description: 'Field-level canonical activity values. Garmin is preferred when available; the original Garmin and Intervals values, selected source, disagreement, and quality flags remain visible.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_id', 'garmin_activity_source_id', 'intervals_activity_source_id', 'distance_source', 'quality_flags'], permittedGroupings: ['sport', 'link_state', 'distance_source'],
+        columns: [column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR'), column('link_state', 'VARCHAR', { filterable: true, groupable: true }), column('garmin_activity_source_id', 'VARCHAR', { filterable: true }), column('intervals_activity_source_id', 'VARCHAR', { filterable: true }), column('garmin_distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('intervals_distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('resolved_distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('distance_source', 'VARCHAR', { filterable: true, groupable: true }), column('garmin_moving_s', 'DOUBLE', { unit: 's', metric: true }), column('intervals_moving_s', 'DOUBLE', { unit: 's', metric: true }), column('resolved_moving_s', 'DOUBLE', { unit: 's', metric: true }), column('moving_s_source', 'VARCHAR', { filterable: true, groupable: true }), column('garmin_elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('intervals_elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('resolved_elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s_source', 'VARCHAR', { filterable: true, groupable: true }), column('garmin_avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('intervals_avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('resolved_avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_hr_source', 'VARCHAR', { filterable: true, groupable: true }), column('provider_distance_difference_m', 'DOUBLE', { unit: 'm', metric: true }), column('quality_flags', 'JSON')],
+    },
+    activity_sources: {
+        name: 'activity_sources', relation: 'activity_sources', description: 'Provider-specific activity identities and source artifact references.', provenanceColumns: ['provider', 'remote_activity_id', 'raw_object_hash'], permittedGroupings: ['provider'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('remote_activity_id', 'VARCHAR', { filterable: true }), column('external_id', 'VARCHAR', { filterable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    activity_summaries: {
+        name: 'activity_summaries', relation: 'activity_summary_facts', description: 'Provider activity summary metrics with activity and timestamp provenance.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'activity_id', 'provider', 'raw_object_hash'], permittedGroupings: ['provider', 'sport'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR', { filterable: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('calories', 'DOUBLE', { unit: 'kcal', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('weighted_power', 'DOUBLE', { unit: 'W', metric: true }), column('avg_cadence', 'DOUBLE', { unit: 'rpm', metric: true }), column('training_load', 'DOUBLE', { metric: true }), column('rpe', 'DOUBLE', { metric: true }), column('feel', 'DOUBLE', { metric: true })],
+    },
+    activity_intervals: {
+        name: 'activity_intervals', relation: 'activity_interval_facts', description: 'Structured intervals attached to an activity source.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'activity_id', 'provider'], permittedGroupings: ['provider', 'sport', 'label'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('interval_key', 'VARCHAR', { filterable: true }), column('label', 'VARCHAR', { filterable: true, groupable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('start_s', 'DOUBLE', { unit: 's', metric: true }), column('end_s', 'DOUBLE', { unit: 's', metric: true }), column('duration_s', 'DOUBLE', { unit: 's', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_pace', 'DOUBLE', { metric: true }), column('intensity', 'DOUBLE', { metric: true })],
+    },
+    swim_lengths: {
+        name: 'swim_lengths', relation: 'swim_length_facts', description: 'Explicit provider-supplied swim-length facts. An empty result means lengths were not supplied; Catence does not infer them from activity samples.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'source', 'confidence', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'source', 'confidence', 'is_rest'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('source', 'VARCHAR', { filterable: true, groupable: true }), column('confidence', 'VARCHAR', { filterable: true, groupable: true }), column('length_index', 'INTEGER', { filterable: true, groupable: true }), column('lap_index', 'INTEGER', { filterable: true, groupable: true }), column('pool_length_m', 'DOUBLE', { unit: 'm', metric: true }), column('start_time', 'TIMESTAMPTZ', { filterable: true }), column('duration_s', 'DOUBLE', { unit: 's', metric: true }), column('active_duration_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('stroke_count', 'DOUBLE', { unit: 'count', metric: true }), column('stroke_rate', 'DOUBLE', { unit: 'strokes/min', metric: true }), column('swolf', 'DOUBLE', { metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('is_rest', 'BOOLEAN', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    swim_sets: {
+        name: 'swim_sets', relation: 'swim_set_facts', description: 'Provider swim groupings. source_type distinguishes Garmin detected/manual groupings from Intervals.icu auto-detected blocks; labels and unprovided durations remain explicit.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'source_type', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'source_type', 'label'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('set_index', 'INTEGER', { filterable: true, groupable: true }), column('label', 'VARCHAR', { filterable: true, groupable: true }), column('reps', 'INTEGER', { metric: true }), column('rep_distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('total_distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('work_s', 'DOUBLE', { unit: 's', metric: true }), column('rest_s', 'DOUBLE', { unit: 's', metric: true }), column('avg_pace', 'DOUBLE', { metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('stroke_rate', 'DOUBLE', { unit: 'strokes/min', metric: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    activity_quality_flags: {
+        name: 'activity_quality_flags', relation: 'activity_quality_flag_facts', description: 'Ingestion-time quality and completeness flags. They flag caveats without deleting or overwriting provider source values.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'flag_code', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'flag_code', 'severity'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('flag_code', 'VARCHAR', { filterable: true, groupable: true }), column('severity', 'VARCHAR', { filterable: true, groupable: true }), column('details_json', 'JSON'), column('raw_object_hash', 'VARCHAR')],
+    },
+    daily_metrics: {
+        name: 'daily_metrics', relation: 'daily_metrics', description: 'Long-form provider daily facts. Metric names and units are explicit.', dateColumn: 'metric_date', provenanceColumns: ['provider', 'raw_object_hash'], permittedGroupings: ['provider', 'metric_name'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('metric_date', 'DATE', { filterable: true, groupable: true }), column('metric_name', 'VARCHAR', { filterable: true, groupable: true }), column('value_number', 'DOUBLE', { metric: true }), column('value_text', 'VARCHAR'), column('unit', 'VARCHAR', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    daily_health: {
+        name: 'daily_health', relation: 'daily_health', description: 'One canonical daily-health record per date. Garmin wins whenever it has facts for that date; Intervals or another provider is a whole-day fallback. Use daily_metrics to compare source observations.', dateColumn: 'metric_date', provenanceColumns: ['provider'], permittedGroupings: ['provider'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('metric_date', 'DATE', { filterable: true, groupable: true }), column('resting_hr_bpm', 'DOUBLE', { unit: 'bpm', metric: true }), column('hrv_ms', 'DOUBLE', { unit: 'ms', metric: true }), column('sleep_seconds', 'DOUBLE', { unit: 's', metric: true }), column('sleep_score', 'DOUBLE', { metric: true }), column('stress', 'DOUBLE', { metric: true }), column('body_battery', 'DOUBLE', { metric: true }), column('readiness', 'DOUBLE', { metric: true }), column('spo2_pct', 'DOUBLE', { unit: '%', metric: true }), column('weight_kg', 'DOUBLE', { unit: 'kg', metric: true }), column('steps', 'DOUBLE', { unit: 'count', metric: true })],
+    },
+    training_metric_observations: {
+        name: 'training_metric_observations', relation: 'training_metric_observations', description: 'Provider training-metric observations. Garmin retains cycling FTP history/settings/activity values and its latest running lactate-threshold power, pace, and heart-rate settings with provenance. Garmin may label its running VO₂max estimate as generic.', dateColumn: 'observed_at', provenanceColumns: ['provider', 'source_type', 'source_remote_id', 'activity_source_id', 'raw_object_hash'], permittedGroupings: ['provider', 'metric_name', 'sport', 'source_type'],
+        columns: [column('observation_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('metric_name', 'VARCHAR', { filterable: true, groupable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('observed_at', 'TIMESTAMPTZ', { filterable: true }), column('value_number', 'DOUBLE', { metric: true }), column('value_text', 'VARCHAR', { filterable: true, groupable: true }), column('unit', 'VARCHAR', { filterable: true, groupable: true }), column('device_id', 'VARCHAR', { filterable: true, groupable: true }), column('dimensions_json', 'JSON'), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('source_remote_id', 'VARCHAR', { filterable: true }), column('activity_source_id', 'VARCHAR', { filterable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    wellness_samples: {
+        name: 'wellness_samples', relation: 'wellness_samples', description: 'Timestamped Garmin health-series samples for heart rate, HRV, stress, and Body Battery.', dateColumn: 'observed_at', provenanceColumns: ['provider', 'source_type', 'source_remote_id', 'raw_object_hash'], permittedGroupings: ['provider', 'metric_name', 'source_type'],
+        columns: [column('sample_id', 'VARCHAR', { filterable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('metric_name', 'VARCHAR', { filterable: true, groupable: true }), column('observed_at', 'TIMESTAMPTZ', { filterable: true }), column('value_number', 'DOUBLE', { metric: true }), column('unit', 'VARCHAR', { filterable: true, groupable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('source_remote_id', 'VARCHAR', { filterable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    health_sessions: {
+        name: 'health_sessions', relation: 'health_sessions', description: 'Garmin sleep, nap, daily-event, and Body Battery event records with their source payload retained.', dateColumn: 'occurred_on', provenanceColumns: ['provider', 'source_type', 'source_remote_id', 'raw_object_hash'], permittedGroupings: ['provider', 'session_type', 'source_type'],
+        columns: [column('session_id', 'VARCHAR', { filterable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('session_type', 'VARCHAR', { filterable: true, groupable: true }), column('occurred_on', 'DATE', { filterable: true, groupable: true }), column('started_at', 'TIMESTAMPTZ', { filterable: true }), column('ended_at', 'TIMESTAMPTZ', { filterable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('source_remote_id', 'VARCHAR', { filterable: true }), column('payload_json', 'JSON'), column('raw_object_hash', 'VARCHAR')],
+    },
+    power_bests: {
+        name: 'power_bests', relation: 'power_best_facts', description: 'Power-duration bests derived from Garmin FIT streams; they are labelled derived while retaining the Garmin activity provenance.', dateColumn: 'started_at_utc', provenanceColumns: ['provider', 'activity_source_id', 'source_type', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'duration_s', 'source_type'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('duration_s', 'INTEGER', { filterable: true, groupable: true }), column('best_power_w', 'DOUBLE', { unit: 'W', metric: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    nutrition_days: {
+        name: 'nutrition_days', relation: 'nutrition_days', description: 'Daily nutrition totals, never a replacement for the item-level food log.', dateColumn: 'nutrition_date', provenanceColumns: ['provider', 'raw_object_hash'], permittedGroupings: ['provider'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('nutrition_date', 'DATE', { filterable: true, groupable: true }), column('energy_kcal', 'DOUBLE', { unit: 'kcal', metric: true }), column('carbohydrates_g', 'DOUBLE', { unit: 'g', metric: true }), column('protein_g', 'DOUBLE', { unit: 'g', metric: true }), column('fat_g', 'DOUBLE', { unit: 'g', metric: true }), column('hydration_ml', 'DOUBLE', { unit: 'ml', metric: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    nutrition_items: {
+        name: 'nutrition_items', relation: 'nutrition_items', description: 'Meal and food-item detail retained from the provider.', dateColumn: 'nutrition_date', provenanceColumns: ['provider', 'remote_item_id', 'raw_object_hash'], permittedGroupings: ['provider', 'meal', 'food_name'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('remote_item_id', 'VARCHAR', { filterable: true }), column('nutrition_date', 'DATE', { filterable: true, groupable: true }), column('meal', 'VARCHAR', { filterable: true, groupable: true }), column('consumed_at', 'TIMESTAMPTZ', { filterable: true }), column('food_name', 'VARCHAR', { filterable: true, groupable: true }), column('quantity', 'DOUBLE', { metric: true }), column('energy_kcal', 'DOUBLE', { unit: 'kcal', metric: true }), column('carbohydrates_g', 'DOUBLE', { unit: 'g', metric: true }), column('protein_g', 'DOUBLE', { unit: 'g', metric: true }), column('fat_g', 'DOUBLE', { unit: 'g', metric: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    events: domain('events', 'event_id', 'Planned and completed calendar events.', 'occurred_on'),
+    workouts: domain('workouts', 'workout_id', 'Provider workouts and scheduled workouts.', 'occurred_on'),
+    workout_documents: {
+        name: 'workout_documents', relation: 'workout_documents', description: 'Structured workout documents.', provenanceColumns: ['provider', 'workout_id'], permittedGroupings: ['provider'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('workout_id', 'VARCHAR', { filterable: true, groupable: true }), column('workout_doc', 'JSON'), column('payload_json', 'JSON')],
+    },
+    training_plans: domain('training_plans', 'training_plan_id', 'Training plans and plan hierarchy.', 'occurred_on'),
+    routes: domain('routes', 'route_id', 'Saved routes.'),
+    gear: domain('gear', 'gear_id', 'Equipment and gear records.'),
+    devices: domain('devices', 'device_id', 'Device metadata and ownership details.'),
+    goals: domain('goals', 'goal_id', 'Goals and challenges.'),
+    achievements: domain('achievements', 'achievement_id', 'Badges and personal records.'),
+    messages: domain('messages', 'message_id', 'Provider chat/messages.', 'occurred_on'),
+    source_entities: {
+        name: 'source_entities', relation: 'source_entities', description: 'All raw-normalized source entities, including fields not modelled elsewhere.', dateColumn: 'occurred_on', provenanceColumns: ['provider', 'entity_type', 'remote_id', 'raw_object_hash'], permittedGroupings: ['provider', 'entity_type'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('entity_type', 'VARCHAR', { filterable: true, groupable: true }), column('remote_id', 'VARCHAR', { filterable: true }), column('parent_remote_id', 'VARCHAR', { filterable: true }), column('occurred_on', 'DATE', { filterable: true, groupable: true }), column('source_updated_at', 'TIMESTAMPTZ', { filterable: true }), column('raw_object_hash', 'VARCHAR'), column('payload_json', 'JSON'), column('extension_json', 'JSON')],
+    },
+    activity_links: {
+        name: 'activity_links', relation: 'activity_links', description: 'Auditable source-to-logical activity links and their evidence.', provenanceColumns: ['activity_source_id', 'method', 'evidence_json'], permittedGroupings: ['method'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('method', 'VARCHAR', { filterable: true, groupable: true }), column('confidence', 'DOUBLE', { metric: true }), column('evidence_json', 'JSON'), column('linked_at', 'TIMESTAMPTZ', { filterable: true })],
+    },
+    activity_segments: {
+        name: 'activity_segments', relation: 'activity_segments', description: 'Strava segment efforts embedded in a hydrated activity; absent values are not inferred.', dateColumn: 'started_at', provenanceColumns: ['activity_source_id', 'effort_id', 'segment_id', 'raw_object_hash'], permittedGroupings: ['segment_id'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('effort_id', 'VARCHAR', { filterable: true, groupable: true }), column('segment_id', 'VARCHAR', { filterable: true, groupable: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('average_watts', 'DOUBLE', { unit: 'W', metric: true }), column('average_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('average_cadence', 'DOUBLE', { unit: 'rpm', metric: true }), column('pr_rank', 'INTEGER', { metric: true }), column('kom_rank', 'INTEGER', { metric: true }), column('started_at', 'TIMESTAMPTZ', { filterable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    segments: {
+        name: 'segments', relation: 'strava_segments', description: 'Hydrated Strava segment facts. Verification is unavailable from the public API and is never inferred.', provenanceColumns: ['segment_id', 'raw_object_hash'], permittedGroupings: ['activity_type', 'climb_category', 'starred', 'private'],
+        columns: [column('segment_id', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR', { filterable: true, groupable: true }), column('activity_type', 'VARCHAR', { filterable: true, groupable: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('average_grade_pct', 'DOUBLE', { unit: '%', metric: true }), column('maximum_grade_pct', 'DOUBLE', { unit: '%', metric: true }), column('climb_category', 'INTEGER', { filterable: true, groupable: true }), column('total_elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('private', 'BOOLEAN', { filterable: true, groupable: true }), column('hazardous', 'BOOLEAN', { filterable: true, groupable: true }), column('starred', 'BOOLEAN', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    segment_effort_history: {
+        name: 'segment_effort_history', relation: 'segment_effort_history', description: 'Authenticated athlete historic Strava segment efforts, hydrated only on demand.', dateColumn: 'started_at', provenanceColumns: ['effort_id', 'segment_id', 'raw_object_hash'], permittedGroupings: ['segment_id', 'climb_category'],
+        columns: [column('effort_id', 'VARCHAR', { filterable: true, groupable: true }), column('segment_id', 'VARCHAR', { filterable: true, groupable: true }), column('strava_activity_id', 'VARCHAR', { filterable: true }), column('segment_name', 'VARCHAR', { filterable: true, groupable: true }), column('average_grade_pct', 'DOUBLE', { unit: '%', metric: true }), column('climb_category', 'INTEGER', { filterable: true, groupable: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('average_speed_mps', 'DOUBLE', { unit: 'm/s', metric: true }), column('average_watts', 'DOUBLE', { unit: 'W', metric: true }), column('average_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('average_cadence', 'DOUBLE', { unit: 'rpm', metric: true }), column('pr_rank', 'INTEGER', { metric: true }), column('kom_rank', 'INTEGER', { metric: true }), column('started_at', 'TIMESTAMPTZ', { filterable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
+    strava_gear: {
+        name: 'strava_gear', relation: 'strava_gear', description: 'Current Strava bikes and shoes, refreshed from the authenticated athlete profile.', provenanceColumns: ['gear_id', 'raw_object_hash'], permittedGroupings: ['provider'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('gear_id', 'VARCHAR', { filterable: true, groupable: true }), column('payload_json', 'JSON'), column('extension_json', 'JSON'), column('raw_object_hash', 'VARCHAR')],
+    },
+    activity_samples: {
+        name: 'activity_samples', description: 'Registered normalized activity samples from immutable Parquet; callers cannot supply file paths.', dateColumn: 'timestamp_utc', provenanceColumns: ['provider', 'activity_source_id', 'content_hash'], permittedGroupings: ['provider', 'activity_source_id'], samplesOnly: true,
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('content_hash', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('timestamp_utc', 'TIMESTAMPTZ', { filterable: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('latitude', 'DOUBLE', { unit: 'degrees', metric: true }), column('longitude', 'DOUBLE', { unit: 'degrees', metric: true }), column('altitude_m', 'DOUBLE', { unit: 'm', metric: true }), column('heart_rate_bpm', 'DOUBLE', { unit: 'bpm', metric: true }), column('power_w', 'DOUBLE', { unit: 'W', metric: true }), column('cadence_rpm', 'DOUBLE', { unit: 'rpm', metric: true }), column('speed_mps', 'DOUBLE', { unit: 'm/s', metric: true }), column('temperature_c', 'DOUBLE', { unit: 'C', metric: true }), column('grade_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_right_balance_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_torque_effectiveness_pct', 'DOUBLE', { unit: '%', metric: true }), column('right_torque_effectiveness_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_pedal_smoothness_pct', 'DOUBLE', { unit: '%', metric: true }), column('right_pedal_smoothness_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_power_phase_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_power_phase_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_power_phase_peak_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_power_phase_peak_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_peak_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_peak_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_platform_center_offset_mm', 'DOUBLE', { unit: 'mm', metric: true }), column('right_platform_center_offset_mm', 'DOUBLE', { unit: 'mm', metric: true }), column('extras_json', 'JSON')],
+    },
+};
+function domain(name, id, description, dateColumn) {
+    return {
+        name, relation: name, description, dateColumn, provenanceColumns: ['provider', id, 'raw_object_hash'], permittedGroupings: ['provider'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column(id, 'VARCHAR', { filterable: true, groupable: true }), ...(dateColumn ? [column(dateColumn, 'DATE', { filterable: true, groupable: true })] : []), column('payload_json', 'JSON'), column('extension_json', 'JSON'), column('raw_object_hash', 'VARCHAR')],
+    };
+}
+export function getDataset(name) {
+    // training_metrics was the original public catalog name. Keep it as a
+    // backwards-compatible input alias, while presenting the actual queryable
+    // relation everywhere so describe_dataset and the SQL allow-list agree.
+    const normalizedName = name === 'training_metrics' ? 'training_metric_observations' : name;
+    const dataset = DATASET_CATALOG[normalizedName];
+    if (!dataset)
+        throw new QueryValidationError(`Unknown dataset: ${name}. Use describe_data to see the catalog.`);
+    return dataset;
+}
+export function getColumn(dataset, name) {
+    const found = dataset.columns.find((columnDefinition) => columnDefinition.name === name);
+    if (!found)
+        throw new QueryValidationError(`${name} is not a cataloged column of ${dataset.name}.`);
+    return found;
+}
+export class QueryValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'QueryValidationError';
+    }
+}
+//# sourceMappingURL=catalog.js.map