catence 0.2.0 → 0.2.1-beta.2

package/README.md

@@ -31,7 +31,7 @@ Install Catence and create the first athlete. The default catalog home is `~/.ca
 Every `catence-data` command requires `--athlete <id>`; there is no default athlete. Pair it with `--home <dir>` to select the catalog when not using the default home.
 
 ```sh
-npm install --global catence@beta          # or catence@latest for stable
+npm install --global catence@latest          # or catence@beta
 catence-data setup --athlete alex --label "Alex"
 ```
 

package/dist/contracts/release.d.ts

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export declare const CATENCE_RUNTIME_VERSION = "0.2.0";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.2";
 export declare const CATENCE_PROTOCOL_VERSION = 1;
 export type CatenceRuntimeCapabilities = {
     mcp: true;

package/dist/contracts/release.js

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export const CATENCE_RUNTIME_VERSION = '0.2.0';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.2';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

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

@@ -1,4 +1,4 @@
-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' | 'activity_decoupling' | '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 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' | 'activity_decoupling' | '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' | 'course_geometry';
 export type CatalogColumn = {
     name: string;
     type: string;

package/dist/core/query/catalog.js

@@ -113,6 +113,10 @@ export const DATASET_CATALOG = {
         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')],
     },
+    course_geometry: {
+        name: 'course_geometry', relation: 'course_geometry', description: 'Per-point Garmin course/route geometry (lat/lon/altitude_m/distance_m) normalized from a race event course. Resolve a courseId first with resolve_event_course, then query these rows for an elevation/height profile, gradient, or GPX-style track.', provenanceColumns: ['course_id', 'raw_object_hash'], permittedGroupings: ['course_id'],
+        columns: [column('course_id', 'VARCHAR', { filterable: true, groupable: true }), column('seq', 'INTEGER', { metric: true }), column('lat', 'DOUBLE', { unit: 'degrees', metric: true }), column('lon', 'DOUBLE', { unit: 'degrees', metric: true }), column('altitude_m', 'DOUBLE', { unit: 'm', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('raw_object_hash', 'VARCHAR')],
+    },
 };
 function domain(name, id, description, dateColumn) {
     return {

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

@@ -44,6 +44,26 @@ function normalizeRelation(name) {
     const relation = name.trim().replace(/\s+(?:as\s+)?(?:"[^"]+"|[A-Za-z_][A-Za-z0-9_]*)\s*$/i, '');
     return relation.replaceAll('"', '').split('.').at(-1).toLowerCase();
 }
+// Physical base tables that are reachable only through cataloged views
+// (e.g. the events/workouts/routes/… domain projections over domain_entities).
+// They must be accepted when DuckDB resolves a cataloged view down to its base
+// table after tableNames(), but must never be writable directly by name.
+const INDIRECT_BASE_TABLES = new Set(['domain_entities']);
+// dataset->named tool hints for the common dead-end relations, so a rejected
+// query tells the agent where to go instead of just that it was denied.
+const RELATION_HINTS = {
+    events: 'events is a domain projection; use aggregate_data on events or resolve_event_course(eventId) / search_context to read events and races.',
+    workouts: 'workouts is a domain projection; use aggregate_data on workouts or search_context to read workouts.',
+    workout_documents: 'workout_documents is a domain projection; use aggregate_data on workout_documents or search_context to read workout documents.',
+    training_plans: 'training_plans is a domain projection; use aggregate_data on training_plans or search_context to read training plans.',
+    routes: 'routes is a domain projection; use aggregate_data on routes or search_context to read routes.',
+    gear: 'gear is a domain projection; use aggregate_data on gear or search_context to read saved gear.',
+    devices: 'devices is a domain projection; use aggregate_data on devices or search_context to read devices.',
+    goals: 'goals is a domain projection; use aggregate_data on goals or search_context to read goals and challenges.',
+    achievements: 'achievements is a domain projection; use aggregate_data on achievements or search_context to read badges and personal records.',
+    messages: 'messages is a domain projection; use aggregate_data on messages or search_context to read provider messages.',
+    course_geometry: 'course_geometry is the per-point course track (lat/lon/altitude_m/distance_m); resolve a race course first with resolve_event_course, then query it for elevation/height profiles.',
+};
 export async function queryReadOnlyData(repository, request) {
     const sql = safeSql(request.sql);
     let relations;
@@ -53,16 +73,28 @@ export async function queryReadOnlyData(repository, request) {
     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()));
+    // The catalog relation names form the strict allow-list for what a query may
+    // name directly (Check B below). Base tables reached only through cataloged
+    // views are additionally permitted after DuckDB resolves views for Check A,
+    // but they are never valid relation names in the SQL text.
+    const allowedNamed = new Set(Object.values(DATASET_CATALOG).filter((dataset) => !dataset.samplesOnly && dataset.relation).map((dataset) => dataset.relation.toLowerCase()));
+    const allowedForExpansion = new Set([...allowedNamed, ...INDIRECT_BASE_TABLES]);
+    const rejected = [];
     for (const relation of relations) {
-        if (!allowed.has(normalizeRelation(relation)))
-            throw new QueryValidationError(`Relation ${relation} is not in the read-only catalog.`);
+        const normalized = normalizeRelation(relation);
+        if (!allowedForExpansion.has(normalized))
+            rejected.push(relation);
+    }
+    if (rejected.length > 0) {
+        const name = normalizeRelation(rejected[0]);
+        throw new QueryValidationError(`Relation ${rejected[0]} is not in the read-only catalog.${RELATION_HINTS[name] ? ` ${RELATION_HINTS[name]}` : ''}`);
     }
     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.`);
+        if (!allowedNamed.has(relation) && !ctes.has(relation)) {
+            throw new QueryValidationError(`Relation ${match[1]} is not in the read-only catalog.${RELATION_HINTS[relation] ? ` ${RELATION_HINTS[relation]}` : ''}`);
+        }
     }
     const values = request.values ?? {};
     if ('__catence_page_size' in values || '__catence_offset' in values)

package/dist/interfaces/mcp/server.js

@@ -31,7 +31,10 @@ const MCP_INSTRUCTIONS = [
     'Never conclude from VO2max alone; pull full indicator set (LT/FTP/power/race-prediction).',
     'When summary metric is NULL (e.g. avg_power), fall through to FIT-derived/samples layer before declaring absence.',
     'Before reusing any prior course/elevation profile, resolve event\'s courseId and diff it against past activity\'s course; different courseId => different profile.',
-    'If a needed tool is not visible in your current tool list (the host may truncate it to a subset), read the catence://tools resource to discover all available tools before concluding a capability is absent.',
+    'If a needed tool is not visible in your current tool list (the host may truncate it to a subset), read the catence://tools resource or call discover_tools to inventory every available tool before concluding a capability is absent.',
+    'To find a next or upcoming race: list dates with aggregate_data on the events dataset (group or filter by occurred_on), identify the event name via search_context or its payload, then call resolve_event_course(eventId) to resolve the courseId and whether that course geometry is synced.',
+    'For a course elevation/height profile or GPX track: call resolve_event_course(eventId) first (it reports the courseId, synced geometry, and geometry sample count), then read the course_geometry dataset with read_series / aggregate_data / query_read_only_data for per-point altitude_m, lat, lon, and distance_m. Never claim a profile is absent before resolve_event_course returns.',
+    'Never treat a tool error or empty result as a dead end: switch strategy or re-read the routing guidance before re-running the same query.',
     'For swim analysis: use find_activities (sports: ["lap_swimming"] or sport: "lap_swimming") to list pool sessions. Use get_swim_laps for per-length data (pace from duration_s/pool_length_m, SPL from stroke_count, SWOLF from duration_s+stroke_count). Use swim_progress_report for session-level SWOLF, fastest-100, and stroke cadence. Per-length SWOLF is derived when the provider does not supply it. Per-length distance is typically null in Garmin FIT; use pool_length_m for pace calculations.',
 ].join(' ');
 function textResult(value) {
@@ -143,9 +146,21 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     // enumerate all tools even when the host harness truncates the visible tool list.
     const TOOL_INDEX = [];
     function registerTool(name, config, callback) {
-        TOOL_INDEX.push({ name, title: config.title ?? name, description: config.description ?? '' });
+        TOOL_INDEX.push({ name, title: config.title ?? name, description: config.description ?? '', keywords: config.keywords ?? [] });
         server.registerTool(name, config, callback);
     }
+    // Keyword-rich routing map surfacing the recommended tool chain per question
+    // domain. Surfaced in catence://tools so a host can navigate without knowing
+    // every tool name up front.
+    const TOOL_ROUTING = [
+        { question: 'next race / upcoming event', steps: ['aggregate_data (events, by occurred_on)', 'search_context', 'resolve_event_course'] },
+        { question: 'course elevation / height profile / GPX track', steps: ['resolve_event_course', 'read_series / aggregate_data (course_geometry)'] },
+        { question: 'swim per-length analysis (pace / SPL / SWOLF)', steps: ['find_activities', 'get_swim_laps', 'swim_progress_report'] },
+        { question: 'segments / climbs / KOM / PR', steps: ['get_activity_segments', 'hydrate_strava_segment_history'] },
+        { question: 'race readiness / fitness targets', steps: ['readiness_baseline', 'analyze_series', 'aggregate_data'] },
+        { question: 'recovery / daily or weekly load', steps: ['review_daily_recovery_load', 'review_weekly_training', 'wellness_baselines'] },
+        { question: 'cycling FTP / VO₂max / power curve', steps: ['get_ftp_history', 'get_vo2max_history', 'power_coverage_report', 'power_curve_trend'] },
+    ];
     const promptAthleteSchema = catalogPaths ? { athleteId: athleteIdSchema } : {};
     if (catalogPaths) {
         registerTool('list_athletes', {
@@ -460,6 +475,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     registerTool('resolve_event_course', {
         title: 'Resolve a race event course and its synced geometry',
         description: 'Given a Garmin/Intervals eventId, return the courseId it references and whether that course geometry has been synced. When geometry is absent, the result carries an explicit caveat so a prior course profile is never reused. Optionally pass pastActivityId to diff the event course against that activity\'s course.',
+        keywords: ['course', 'race course', 'event course', 'elevation profile', 'height profile', 'GPX track', 'course geometry', 'gradient', 'climb', 'GPS track'],
         inputSchema: { eventId: z.string().min(1), pastActivityId: z.string().min(1).optional() },
     }, tool('resolve_event_course', async (input) => useRepository(activePaths(), async (repository) => {
         const events = new EventsService(repository);
@@ -479,6 +495,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     registerTool('find_activities', {
         title: 'Find activities and likely races',
         description: 'Find canonical activities by sport, distance, name, and date. Results are paginated and transparently flag likely-race signals without claiming provider-confirmed race metadata. Read-only.',
+        keywords: ['race', 'races', 'next race', 'events', 'upcoming event', 'activity list', 'swim sessions', 'pool sessions', 'laps', 'recent runs'],
         inputSchema: {
             sport: z.string().min(1).optional(),
             sports: z.array(z.string().min(1)).min(1).max(12).optional(),
@@ -491,16 +508,19 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     registerTool('get_swim_laps', {
         title: 'Read explicit swim lengths and grouped sets',
         description: 'Return source-aware swim lengths when a provider actually supplied them, plus Garmin detected and Intervals.icu auto-detected sets. A missing length list is reported as unavailable; laps are never reconstructed from samples.',
+        keywords: ['swim', 'swimming', 'per-length', 'pace', 'SPL', 'SWOLF', 'pool', 'lengths', 'laps', 'cadence'],
         inputSchema: { activityId: z.string().min(1), provider: z.enum(['garmin', 'intervals']).optional() },
     }, tool('get_swim_laps', async (input) => useRepository(activePaths(), (repository) => new SwimmingService(repository).swimLaps(input))));
     registerTool('swim_progress_report', {
         title: 'Build a source-aware swim progress report',
         description: 'Compare Garmin swimming summaries and data completeness over a date range, optionally within one pool length. It does not derive pace trends from moving time divided by distance.',
+        keywords: ['swim', 'swimming', 'progress', 'SWOLF', 'fastest 100', 'cadence', 'pool length', 'swim trends'],
         inputSchema: { startDate: z.string().date().optional(), endDate: z.string().date().optional(), poolLengthM: z.number().positive().max(200).optional() },
     }, tool('swim_progress_report', async (input) => useRepository(activePaths(), (repository) => new SwimmingService(repository).swimProgressReport(input))));
     registerTool('get_activity_segments', {
         title: 'Hydrate and read an activity’s Strava segments',
         description: 'For a selected activity’s segments, climbs, KOM/PRs, or per-segment analysis: automatically hydrate the matching Strava activity before returning its persisted segment efforts. Use this before saying segment data is unavailable.',
+        keywords: ['segments', 'climbs', 'KOM', 'PR', 'grade by segment', 'Strava segments', 'segment efforts', 'per-segment analysis'],
         inputSchema: { activityId: z.string().min(1), refresh: z.boolean().optional(), limit: z.number().int().min(1).max(500).optional() },
     }, tool('get_activity_segments', async (input) => {
         const hydration = await hydrateActivity(activePaths(), input.activityId, input.refresh ?? false);
@@ -542,6 +562,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     }, tool('query_read_only_data', async (input) => useRepository(activePaths(), (repository) => queryReadOnlyData(repository, input))));
     registerTool('search_context', {
         title: 'Search generated context', description: 'Search compact generated activity, plan, nutrition, and message context. Results identify authoritative follow-up tools rather than making numerical claims.',
+        keywords: ['event name', 'race name', 'course', 'elevation', 'GPX', 'activity summary', 'plan', 'nutrition', 'find the event'],
         inputSchema: { query: z.string().min(2).max(500), filters: z.array(z.object({ column: z.enum(['provider', 'entity_type', 'occurred_on']), op: z.enum(['eq', 'in', 'between']), value: z.unknown() })).max(20).optional(), limit: z.number().int().min(1).max(50).optional() },
     }, tool('search_context', async (input) => useRepository(activePaths(), (repository) => searchContext(repository, input))));
     registerTool('hydrate_strava_activity', {
@@ -628,6 +649,19 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         const data = await hydrateStravaSegmentHistory(activePaths(), input.segmentId, input.refresh ?? false);
         return { data, coverage: await useRepository(activePaths(), (repository) => repository.coverage()), provenance: { provider: 'strava', operation: 'segment_effort_history', archivedBeforeNormalization: true }, caveats: ['Only the authenticated athlete’s historic segment efforts are requested.'] };
     }));
+    // Registered last so every tool above is present in the tool index before its
+    // one-line catalog is baked into this tool's description. Survives host tool
+    // truncation because tool descriptions are always visible to the model.
+    registerTool('discover_tools', {
+        title: 'Discover all Catence tools and routing',
+        description: [
+            'Inventory the full Catence tool surface even when the host truncates its visible tool list. Query by question: next race/upcoming event (aggregate_data on events, search_context, resolve_event_course), course elevation/height profile/GPX (resolve_event_course then read_series or aggregate_data on course_geometry), swim per-length pace/SPL/SWOLF (find_activities, get_swim_laps, swim_progress_report), segments/climbs/KOM/PR (get_activity_segments), race readiness (readiness_baseline), recovery (review_daily_recovery_load, review_weekly_training), cycling FTP/VO₂max/power (get_ftp_history, get_vo2max_history, power_coverage_report, power_curve_trend).',
+            ...TOOL_INDEX.map((entry) => `${entry.name} — ${entry.title}`),
+        ].join('\n'),
+    }, tool('discover_tools', async () => ({
+        data: { count: TOOL_INDEX.length, routing: TOOL_ROUTING, tools: TOOL_INDEX.map((entry) => ({ name: entry.name, purpose: entry.title, keywords: entry.keywords })) },
+        provenance: { catalog: 'Catence tool index' }, query: {}, caveats: ['Use this to map a question to its named tool before falling back to SQL.'],
+    })));
     if (catalogPaths) {
         server.registerResource('athletes', 'catence://athletes', { title: 'Configured athlete roster', mimeType: 'application/json' }, async (uri) => {
             try {
@@ -680,7 +714,8 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         return resource(uri, {
             count: TOOL_INDEX.length,
             note: 'If a needed tool is not visible in your current tool list (the host may truncate it), use this index to discover all available tools before concluding a capability is absent. SQL-only tables training_metric_observations and source_entities are reachable via query_read_only_data / describe_data.',
-            tools: TOOL_INDEX.map((tool) => ({ name: tool.name, purpose: tool.title, description: tool.description })),
+            routing: TOOL_ROUTING,
+            tools: TOOL_INDEX.map((tool) => ({ name: tool.name, purpose: tool.title, description: tool.description, keywords: tool.keywords })),
         });
     });
     return server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0",
+  "version": "0.2.1-beta.2",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -82,8 +82,9 @@
     "vitest": "^3.2.4"
   },
   "overrides": {
-    "fast-uri": "3.1.5",
+    "fast-uri": "3.1.7",
     "hono": "4.12.34",
-    "nanoid": "3.3.18"
+    "nanoid": "3.3.18",
+    "qs": "6.16.0"
   }
 }