catence 0.2.0-beta.8 → 0.2.0

package/docs/mcp-activity-retrieval.md

@@ -102,19 +102,16 @@ sessions, active-length/distance mismatches, linked-provider distance
 disagreements, and missing explicit length records. Flags are caveats; they
 never overwrite or discard a provider's source values.
 
-## Current investigation procedure
-
-Use this procedure until the endpoints below exist.
+## Investigation procedure
 
 1. Check `catence_status`. If the sync snapshot is unavailable, report the MCP
    error; do not retry by opening the database for writing.
-2. List provider records from newest to oldest with `activities` joined to
-   `activity_sources` and, where needed, `activity_summary_facts`. Include
-   both the logical and source IDs in the result.
-3. For one selected source, query `activity_interval_facts` ordered by
-   `start_s`. Do not use a time/distance heuristic to select a different
-   source.
-4. If a provider’s interval rows are empty or all structural fields are null,
+2. Use `find_activities` to list provider records filtered by sport, distance,
+   name, or date. Results are paginated and return both logical and source IDs.
+3. For a selected source, call `get_activity_segments` for intervals, laps,
+   or structured splits — it automatically hydrates the matching Strava activity
+   when needed.
+4. If a provider's interval rows are empty or all structural fields are null,
    say that detailed splits were not supplied by that imported endpoint. A
    summary field such as Garmin's lap count or fastest split is still useful,
    but it does **not** reconstruct per-lap records.
@@ -122,6 +119,8 @@ Use this procedure until the endpoints below exist.
    `activity_source_id`; include its resolution/downsampling caveat. The
    original activity file may exist in the raw archive, but raw archives are
    not exposed directly to MCP in this release.
+6. For aerobic decoupling or grade-adjusted pace, call `activity_decoupling`.
+   For race-readiness questions, call `readiness_baseline` first.
 
 ### Segment calculations
 
@@ -140,15 +139,55 @@ as `no_distance_segment`; calling it a recovery/rest requires a source label
 or a clearly labelled user interpretation. If the sum of chunk distances
 differs from the activity summary, report both values and the difference.
 
-## Proposed dedicated MCP endpoints
+## Activity discovery, detail, and stream endpoints
+
+The originally proposed `list_recent_activities`, `get_activity_detail`,
+`list_activity_segments`, and `read_activity_stream` endpoints (see the
+[design notes](#design-notes-for-original-endpoints) below) were implemented
+as registered tools under different names that better reflect their final
+scope.
+
+### `find_activities`
+
+Compact, canonical, paginated activity/race discovery by sport, distance, name,
+and date. Filters include `sport`/`sports`, `distanceKm` (min/max tuple),
+`nameContains`, and `startDate`/`endDate`. Results are sorted by date
+(descending by default) with opaque cursor pagination. Race flags are
+transparent heuristics, not provider-confirmed race metadata.
+
+### `get_activity_segments`
+
+The required segment/climb path. Performs targeted Strava hydration before
+returning persisted effort and segment facts; an empty result must be
+interpreted alongside its hydration status. Accepts an `activityId` (logical)
+and returns segment efforts, climbs, KOM/PRs, and per-segment analysis.
 
-These endpoints are drafts, not registered tools yet. Add them incrementally
-only after their shared service methods and fixture tests exist.
+### `review_activity_deep_dive`
 
-## Implemented fitness and hydration endpoints
+Returns canonical activity identity, source summaries, and structured intervals
+for a single `activityId`. Call `read_series` separately only when a specific
+sampled metric is required.
+
+### `read_series` (sample-level inspection)
+
+Available through `read_series({ dataset: "activity_samples" })` for
+one `activity_source_id`. Inherits the 1,000-point page limit, cursor format,
+automatic downsampling, manifest-only Parquet access, and null handling. Returns
+no data — not an error — when the source has no registered stream, with a caveat
+explaining that sample availability is provider/activity-specific.
+
+### `get_swim_laps`
+
+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.
+
+## Fitness, readiness, and derived-metrics endpoints
 
 - `describe_dataset(dataset)` returns one cataloged schema and its coverage. `training_metric_observations` also reports its observed sports, metric names, units, and source types.
 - `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, and `power_coverage_report` read normalized, source-aware fitness facts. Power tools require an explicit sport or sport family, use `power_bests`/`power_best_facts` for FIT-derived duration values, and do not treat sparse `avg_power` summaries as coverage. `get_vo2max_history` does not default to cycling: omission returns available source labels and requires an explicit choice. For Garmin running VO₂max, request `sport: "running"`; the tool reads the raw `generic` source series and preserves that label on returned observations.
+- `readiness_baseline` combines the full running/race performance-indicator set in one call: running lactate threshold (pace/power/HR), VO₂max, race predictions, fitness trend, endurance score, and FIT-derived power bests/coverage as trends. Use this before any single-activity comparison for race-readiness or fitness-target questions.
+- `activity_decoupling` derives aerobic decoupling (Pa:Hr for running using speed/HR, Pw:Hr for cycling using power/HR — drift across steady first/second halves) and grade-adjusted pace (GAP, Minetti 2002 cost model) from stored `activity_samples`. Returns null with explanatory caveats when samples are insufficient, walk-heavy, or stop-heavy. Derived values are descriptive only and never overwrite provider-supplied decoupling/GAP. Pass `includeGap: false` to skip GAP computation.
 - `find_activities` is implemented for compact, canonical, paginated activity/race discovery by sport, distance, name, and date. Its race flags are transparent heuristics, not provider-confirmed race metadata.
 - `get_activity_segments` is the required segment/climb path. It performs the
   targeted Strava hydration before returning the persisted effort and segment
@@ -157,6 +196,10 @@ only after their shared service methods and fixture tests exist.
 - `cycling_progress_report` composes the preceding read-only outputs with monthly canonical volume/load. It is descriptive, not a physiological model.
 - `hydrate_recent_strava_activities` accepts an explicit list or a bounded date/sport window and awaits each write in sequence. Its unmatched output includes the exact Strava search window and safe-match rejection diagnostics.
 
+## Events and race course endpoints
+
+- `resolve_event_course` takes a Garmin/Intervals `eventId` and returns the `courseId` it references plus 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 profile.
+
 ### Power investigation procedure
 
 For a question about running or cycling power, do not begin with
@@ -172,206 +215,43 @@ null even when the FIT stream has power. Instead:
    specific extreme needs validation. Raw sample reads are paginated and are
    not evidence that the global power dataset is absent.
 
-### `list_recent_activities`
-
-Purpose: answer “what is my latest activity?” without requiring the agent to
-invent joins, provider precedence, or identifier handling.
-
-Input:
-
-```ts
-{
-  before?: string,              // ISO timestamp; exclusive cursor anchor
-  after?: string,               // ISO timestamp; inclusive
-  provider?: "garmin" | "intervals",
-  sport?: string,
-  sourceMode?: "source" | "logical", // default: "source"
-  limit?: number,               // 1–100; default: 20
-  cursor?: string
-}
-```
-
-`sourceMode: "source"` is the default because it never conceals an unlinked
-provider record. It returns one provider source per item. `sourceMode:
-"logical"` returns an activity plus all its source records only when the
-database already has that logical relationship; unlinked records remain
-separate items. Both modes sort by `started_at_utc DESC`, then stable source
-identity. Cursor contents are opaque, signed/validated query state—not a raw
-SQL offset.
-
-Each item should include:
-
-```ts
-{
-  activityId: string,
-  activitySourceId: string,
-  provider: "garmin" | "intervals",
-  remoteActivityId: string,
-  externalId: string | null,
-  linkState: string,
-  startedAtUtc: string | null,
-  startedAtLocal: string | null,
-  timezone: string | null,
-  sport: string | null,
-  name: string | null,
-  summary: {
-    distanceM: number | null,
-    movingS: number | null,
-    elapsedS: number | null,
-    avgHr: number | null,
-    maxHr: number | null,
-    trainingLoad: number | null
-  } | null,
-  availability: { intervals: boolean, samples: boolean }
-}
-```
-
-The query is a read-only projection of `activities`, `activity_sources`,
-`activity_summary_facts`, and `stream_manifest`. It must not use
-`canonical_activity_training` to suppress a Garmin source. Provenance names
-the selected relations and source artifact hash where available.
-
-### `get_activity_detail`
-
-Purpose: return the compact, authoritative detail an agent needs after a
-selection from `list_recent_activities`.
-
-Input is exactly one of:
+## Agent workflow
 
-```ts
-{ activitySourceId: string, include?: ["summary", "intervals", "availability"] }
-// or
-{ activityId: string, include?: ["summary", "intervals", "availability"] }
-```
-
-`activitySourceId` returns exactly that provider record. `activityId` returns
-the logical activity plus **all** linked sources; it never selects a “best”
-source silently. The default includes `summary` and `availability`, not every
-interval. Intervals are limited to 500 items and receive deterministic cursor
-pagination. A compact response should contain activity identity/timestamps,
-source identities and external IDs, all available provider summaries, and:
-
-```ts
-availability: {
-  intervalCount: number,
-  intervalDetailsAvailable: boolean,
-  stream: { available: boolean, rowCount?: string, columns?: string[] },
-  originalArchiveRecorded: boolean
-}
-```
-
-`originalArchiveRecorded` only states that a raw object/manifest exists. It
-does not expose a filesystem path or claim that FIT parsing supplied laps.
-`include: ["intervals"]` follows the segment contract below.
-
-### `list_activity_segments`
-
-Purpose: replace the manual interval query used for lap/interval questions.
-It should have a neutral name because source “intervals”, swim laps, and
-device splits have different meanings.
-
-Input:
-
-```ts
-{
-  activitySourceId: string,
-  kind?: "all" | "structured_interval" | "lap_or_split", // default: "all"
-  includeDerived?: boolean,  // default: true
-  limit?: number,            // 1–500; default: 100
-  cursor?: string
-}
-```
-
-`kind` filters only by explicit source classification. It must return an
-empty result with `lap_or_split_available: false` when the provider supplied
-no detailed split records; it must not manufacture laps from sample points.
-
-For each item return source fields (`intervalKey`, `label`, `startS`, `endS`,
-`distanceM`, `avgHr`, `avgPower`, `avgPace`, `intensity`, and optionally
-`metricsJson`) plus safe derived fields:
-
-```ts
-{
-  derived: {
-    durationS: number | null,
-    paceSPer100m: number | null,
-    distanceClass: "positive_distance" | "no_distance" | "unknown"
-  }
-}
-```
-
-The top-level result includes total supplied distance, total derived distance,
-summary distance, and their difference. It must explicitly disclose whether
-the response is made of structured intervals, provider laps/splits, or both.
+For a question like "how did this go in the context of my recent swims?" an
+agent should:
 
-### `read_activity_stream`
-
-Purpose: make selected-source sample inspection straightforward while retaining
-the existing bounded stream rules.
-
-Input:
-
-```ts
-{
-  activitySourceId: string,
-  metrics: Array<"elapsed_s" | "distance_m" | "heart_rate_bpm" |
-                 "power_w" | "cadence_rpm" | "speed_mps" | "temperature_c">,
-  resolution?: "raw" | "1m" | "5m" | "15m" | "auto",
-  startElapsedS?: number,
-  endElapsedS?: number,
-  pageSize?: number,
-  cursor?: string
-}
-```
-
-This is a source-ID wrapper over `read_series({ dataset: "activity_samples" })`.
-It inherits the 1,000-point page limit, cursor format, automatic downsampling,
-manifest-only Parquet access, and null handling. It returns no data—not an
-error—when the source has no registered stream, with a caveat explaining that
-sample availability is provider/activity-specific.
-
-## Intended agent behaviour
-
-For “how did this go in the context of my recent swims?” an agent should:
-
-1. Use `list_recent_activities` filtered to swimming to identify the selected
-   source and comparable source records.
-2. Use `get_activity_detail` for the selected source. Prefer canonical
+1. Use `find_activities` filtered to swimming to identify the selected source
+   and comparable source records.
+2. Use `review_activity_deep_dive` for the selected activity. Prefer canonical
    Intervals training values only when the logical activity is strongly linked;
    otherwise state the provider used.
-3. Use `list_activity_segments` only for set/lap questions. Compute pace using
+3. Use `get_activity_segments` only for set/lap questions. Compute pace using
    the documented formula, name it as derived, and do not call unlabelled
-   sections “recovery” as a fact.
-4. Use `read_activity_stream` when the summary/segments cannot answer a
-   question about HR evolution, temperature, or other sample-level behaviour.
-5. State missing data and provenance in the answer. Do not imply that an empty
-   Garmin split list means no laps occurred—only that detailed split records
+   sections "recovery" as a fact.
+4. Use `read_series` with `dataset: "activity_samples"` when the
+   summary/segments cannot answer a question about HR evolution, temperature,
+   or other sample-level behaviour.
+5. For race-readiness questions, call `readiness_baseline` first to establish
+   the fitness context before any single-activity comparison.
+6. For aerobic decoupling or grade-adjusted pace, call `activity_decoupling`.
+7. State missing data and provenance in the answer. Do not imply that an empty
+   Garmin split list means no laps occurred — only that detailed split records
    were not returned by the imported endpoint.
 
-## Implementation order and acceptance criteria
-
-1. Add repository methods that return typed source-first activity records and
-   manifest availability. Keep SQL there; MCP handlers remain thin.
-2. Implement `list_recent_activities`, including stable ordering and tamper-
-   resistant cursor validation.
-3. Implement `get_activity_detail` and `list_activity_segments` against the
-   repository methods. Reuse the existing JSON-safe result/error envelope.
-4. Add `read_activity_stream` as a validated adapter to `AnalyticsService`;
-   do not duplicate downsampling or Parquet path checks.
-5. Add Zod schemas and one independent module/test file per tool. Update the
-   catalog/README once the tools are registered.
-
-Fixture tests must cover:
-
-- two unlinked Garmin/Intervals records with similar timestamps and distances;
-  list results remain distinct;
-- a truly strong-ID-linked activity; detail returns both sources without
-  concealing either;
-- labelled intervals, unlabelled positive-distance chunks, and no-distance
-  chunks; pace is derived only when valid;
-- a Garmin summary with lap count/fastest split but an empty split list;
-  `lap_or_split_available` is false and no laps are invented;
-- no stream manifest, missing Parquet file, and a valid registered stream;
-- pagination, malformed/tampered cursors, limits, and read-only snapshot
-  errors;
-- response provenance and caveats for every branch.
+## Design notes for original endpoints
+
+The originally proposed `list_recent_activities`, `get_activity_detail`,
+`list_activity_segments`, and `read_activity_stream` endpoints were designed
+before the registered tools existed. Their semantic intent is preserved in the
+implemented tools described above, under different names that reflect their
+final scope:
+
+| Proposed name | Implemented as | Notes |
+|---|---|---|
+| `list_recent_activities` | `find_activities` | Adds sport/distance/name filters, opaque cursor pagination |
+| `get_activity_detail` | `review_activity_deep_dive` + `get_activity_segments` | Detail split across review and segment tools |
+| `list_activity_segments` | `get_activity_segments` | Includes automatic Strava hydration |
+| `read_activity_stream` | `read_series({ dataset: "activity_samples" })` | Source-ID validation added in the handler |
+
+The original input/output contracts (see git history) remain useful as
+specifications for acceptance criteria in fixture tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.8",
+  "version": "0.2.0",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {

package/pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
 
 [tool.uv.sources]
 # fork commit
-garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "732bf14602bce2ca22cb569ba6583c3229bf904d" }
+garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "cd4e3d9ef81a93681950138e08f57af226fd5735" }
 
 [tool.uv]
 package = false

package/python/catence/providers/garmin/cli.py

@@ -4,11 +4,14 @@ import argparse
 import getpass
 import json
 import os
+import signal
+import sys
 from datetime import date
 from pathlib import Path
 
+from .progress import ProgressReporter
 from .staging import StagingWriter
-from .worker import GarminStagingWorker
+from .worker import GarminStagingWorker, WorkerInterrupted
 
 
 def parse_args() -> argparse.Namespace:
@@ -26,6 +29,17 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--historical-only", action="store_true", help="Skip current account and collection endpoints.")
     parser.add_argument("--skip-daily", action="store_true", help="Do not fetch date-scoped daily data.")
     parser.add_argument("--skip-activities", action="store_true", help="Do not fetch date-scoped activities.")
+    parser.add_argument(
+        "--lt-history-from",
+        dest="lt_history_from",
+        type=date.fromisoformat,        help="Backfill lactate-threshold history from this date instead of the daily window.",
+    )
+    parser.add_argument(
+        "--events-from",
+        dest="events_from",
+        type=date.fromisoformat,
+        help="Fetch calendar events from this date instead of the default short lookback.",
+    )
     return parser.parse_args()
 
 
@@ -43,19 +57,39 @@ def main() -> None:
     token_store.parent.mkdir(parents=True, exist_ok=True)
     client = Garmin(email, password, prompt_mfa=lambda: input("Garmin MFA code: "))
     client.login(str(token_store))
+    reporter = ProgressReporter(args.run_id)
+    reporter.set_stage("login")
+    reporter.finish("login")
     known_hashes: dict[str, str] = {}
     if args.known_activities and args.known_activities.exists():
         loaded = json.loads(args.known_activities.read_text(encoding="utf-8"))
         if isinstance(loaded, dict):
             known_hashes = {str(key): str(value) for key, value in loaded.items()}
-    GarminStagingWorker(client, writer, args.data_dir, known_hashes).sync(
-        daily_from_date=None if args.skip_daily else args.daily_from_date or args.from_date,
-        activity_from_date=None if args.skip_activities else args.activity_from_date or args.from_date,
-        to_date=args.to_date,
-        daily_to_date=args.daily_to_date,
-        activity_to_date=args.activity_to_date,
-        include_non_historical=not args.historical_only,
-    )
+    worker = GarminStagingWorker(client, writer, args.data_dir, known_hashes, progress=reporter)
+    interrupt_signal: int | None = None
+
+    def _request_interrupt(signum: int, _frame: object) -> None:
+        nonlocal interrupt_signal
+        interrupt_signal = signum
+        worker.request_interrupt()
+
+    signal.signal(signal.SIGINT, _request_interrupt)
+    signal.signal(signal.SIGTERM, _request_interrupt)
+    try:
+        worker.sync(
+            daily_from_date=None if args.skip_daily else args.daily_from_date or args.from_date,
+            activity_from_date=None if args.skip_activities else args.activity_from_date or args.from_date,
+            to_date=args.to_date,
+            daily_to_date=args.daily_to_date,
+            activity_to_date=args.activity_to_date,
+            include_non_historical=not args.historical_only,
+            lactate_threshold_history_from=args.lt_history_from,
+            events_from=args.events_from.isoformat() if args.events_from else None,
+        )
+    except WorkerInterrupted:
+        reporter.finish("interrupted")
+        raise SystemExit(130 if interrupt_signal == signal.SIGINT else 143)
+    reporter.finish("completed")
 
 
 if __name__ == "__main__":

package/python/catence/providers/garmin/progress.py

@@ -0,0 +1,85 @@
+"""Progress reporting for Garmin sync runs.
+
+Emits single-line JSON progress records (kind: 'progress') on stdout so the
+Node management layer can persist heartbeats without parsing the staging
+JSONL consumed by the importer.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+
+class ProgressReporter:
+    """Throttled progress publisher writing NDJSON records to stdout."""
+
+    def __init__(
+        self,
+        run_id: str,
+        provider: str = "garmin",
+        emit: Callable[[str], None] = lambda line: print(line, flush=True),
+        interval_seconds: float = 2.0,
+    ) -> None:
+        self.run_id = run_id
+        self.provider = provider
+        self.emit = emit
+        self.interval_seconds = interval_seconds
+        self._started = time.monotonic()
+        self._last_emitted = 0.0
+        self.stage = "starting"
+        self.current_step: str | None = None
+        self.completed_units = 0
+        self.total_units: int | None = None
+
+    def set_stage(self, stage: str) -> None:
+        """Switch phases, resetting phase-local counters and forcing a publish."""
+        if stage != self.stage:
+            self.stage = stage
+            self.current_step = None
+            self.completed_units = 0
+            self.total_units = None
+            self.publish(force=True)
+
+    def advance(self, completed: int | None = None, total: int | None = None, step: str | None = None) -> None:
+        if completed is not None:
+            self.completed_units = completed
+        if total is not None:
+            self.total_units = total
+        if step is not None:
+            self.current_step = step
+        self.publish()
+
+    def publish(self, force: bool = False) -> None:
+        now = time.monotonic()
+        if not force and now - self._last_emitted < self.interval_seconds:
+            return
+        self._last_emitted = now
+        elapsed = now - self._started
+        percent = 0.0
+        eta: float | None = None
+        if self.total_units and self.total_units > 0:
+            percent = min(100.0, max(0.0, self.completed_units / self.total_units * 100.0))
+            if self.completed_units > 0 and self.completed_units < self.total_units:
+                rate = elapsed / self.completed_units
+                eta = rate * (self.total_units - self.completed_units)
+        record = {
+            "kind": "progress",
+            "runId": self.run_id,
+            "provider": self.provider,
+            "stage": self.stage,
+            "currentStep": self.current_step,
+            "completedUnits": self.completed_units,
+            "totalUnits": self.total_units,
+            "percentComplete": round(percent, 2),
+            "elapsedSeconds": round(elapsed, 1),
+            "estimatedRemainingSeconds": round(eta, 1) if eta is not None else None,
+            "heartbeatAt": datetime.now(timezone.utc).isoformat(),
+        }
+        self.emit(json.dumps(record, separators=(",", ":")))
+
+    def finish(self, stage: str = "completed") -> None:
+        self.stage = stage
+        self.publish(force=True)

package/python/catence/providers/garmin/registry.py

@@ -32,6 +32,8 @@ GARMIN_READ_METHODS = {
         "get_activity_gear", "download_activity",
     ),
     "workouts": ("get_workouts", "get_scheduled_workouts"),
+    "events": ("get_events",),
+    "course": ("connectapi",),
     "goals": ("get_goals",),
     "gear": ("get_gear",),
     "golf": ("get_golf_summary",),

package/python/catence/providers/garmin/streams.py

@@ -183,6 +183,44 @@ def fit_archive_to_samples(activity_source_id: str, archive: Path) -> list[dict[
         return []
 
 
+def fit_archive_to_swim_lengths(activity_source_id: str, archive: Path) -> list[dict[str, Any]]:
+    """Best-effort per-length parsing from the FIT 'length' messages; malformed/unavailable archives yield no rows."""
+    try:
+        import fitdecode
+        with zipfile.ZipFile(archive) as zip_file:
+            fit_name = next((name for name in zip_file.namelist() if name.lower().endswith(".fit")), None)
+            if not fit_name:
+                return []
+            with zip_file.open(fit_name) as stream, fitdecode.FitReader(stream) as reader:
+                rows: list[dict[str, Any]] = []
+                for frame in reader:
+                    if not isinstance(frame, fitdecode.records.FitDataMessage) or frame.name != "length":
+                        continue
+                    fields = {field.name: field.value for field in frame.fields}
+                    length_type = str(fields.get("length_type") or "").lower()
+                    start_time = fields.get("start_time") or fields.get("timestamp")
+                    row = {
+                        "lengthIndex": _number(fields.get("message_index")),
+                        "lapIndex": None,
+                        "startTime": start_time.isoformat().replace("+00:00", "Z") if hasattr(start_time, "isoformat") else None,
+                        "durationS": _number(fields.get("total_elapsed_time") or fields.get("total_timer_time")),
+                        "activeDurationS": _number(fields.get("total_timer_time")),
+                        "distanceM": _number(fields.get("distance")),
+                        "strokeCount": _number(fields.get("total_strokes")),
+                        "strokeRate": _number(fields.get("avg_swimming_cadence") or fields.get("avg_cadence")),
+                        "swolf": _number(fields.get("avg_swolf")),
+                        "avgHr": _number(fields.get("avg_heart_rate") or fields.get("average_heart_rate")),
+                        "maxHr": _number(fields.get("max_heart_rate")),
+                        "isRest": length_type in {"rest", "idle", "pause"},
+                        "label": str(fields.get("swim_stroke") or "").lower() or None,
+                        "raw": {name: (value.isoformat().replace("+00:00", "Z") if hasattr(value, "isoformat") else value) for name, value in fields.items()},
+                    }
+                    rows.append(row)
+                return rows
+    except (ImportError, OSError, ValueError, zipfile.BadZipFile):
+        return []
+
+
 def write_parquet(data_dir: Path, activity_id: str, start_date: str, samples: Iterable[dict[str, Any]]) -> tuple[Path, str, int]:
     records = list(samples)
     year, month = (start_date[:4] or "unknown"), (start_date[5:7] or "unknown")