catence 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -6,9 +6,14 @@ import hashlib
 import json
 from typing import Any, Callable, Mapping
 
+from .progress import ProgressReporter
 from .registry import GARMIN_READ_METHODS, assert_read_only_registry
 from .staging import StagingWriter
-from .streams import SAMPLE_COLUMNS, activity_details_to_samples, activity_power_bests, fit_archive_to_samples, write_parquet
+from .streams import SAMPLE_COLUMNS, activity_details_to_samples, activity_power_bests, fit_archive_to_samples, fit_archive_to_swim_lengths, write_parquet
+
+
+class WorkerInterrupted(Exception):
+    """Raised between extraction steps when the run is asked to stop."""
 
 
 def as_dict(value: Any) -> dict[str, Any]:
@@ -39,6 +44,52 @@ def functional_threshold_power_items(value: Any) -> list[dict[str, Any]]:
     return []
 
 
+def threshold_range_items(value: Any) -> list[dict[str, Any]]:
+    """Extract dated points from a lactate-threshold range series response."""
+    items = functional_threshold_power_items(value)
+    return [item for item in items if isinstance(item.get("value"), (int, float)) and not isinstance(item.get("value"), bool)]
+
+
+def lactate_threshold_days(payload: Any) -> dict[str, dict[str, float]]:
+    """Combine speed/heart-rate and power range series into per-day thresholds.
+
+    The range responses carry no weight or power-to-weight fields; deriving
+    W/kg is left to downstream joins against daily weight history.
+    """
+    combined: dict[str, dict[str, float]] = {}
+    if not isinstance(payload, Mapping):
+        return combined
+    for block, key in (("speed", "speed"), ("heart_rate", "heartRate")):
+        for item in threshold_range_items(payload.get(block)):
+            day = ftp_history_date(item)
+            if day:
+                combined.setdefault(day, {})[key] = float(item["value"])
+    for item in threshold_range_items(payload.get("power")):
+        day = ftp_history_date(item)
+        if day:
+            combined.setdefault(day, {})["functionalThresholdPower"] = float(item["value"])
+    return combined
+
+
+def lactate_threshold_payload(day: str, threshold: Mapping[str, float]) -> dict[str, Any]:
+    """Compose a singleton-shaped payload the normalizer already understands."""
+    observed_at = f"{day}T12:00:00"
+    payload: dict[str, Any] = {"calendarDate": observed_at}
+    speed = threshold.get("speed")
+    heart_rate = threshold.get("heartRate")
+    power = threshold.get("functionalThresholdPower")
+    if speed is not None or heart_rate is not None:
+        speed_and_heart_rate: dict[str, Any] = {"calendarDate": observed_at}
+        if speed is not None:
+            speed_and_heart_rate["speed"] = speed
+        if heart_rate is not None:
+            speed_and_heart_rate["heartRate"] = heart_rate
+        payload["speed_and_heart_rate"] = speed_and_heart_rate
+    if power is not None:
+        payload["power"] = {"calendarDate": observed_at, "functionalThresholdPower": power, "origin": "RUNNING"}
+    return payload
+
+
 def ftp_history_date(payload: Mapping[str, Any]) -> str | None:
     for key in ("until", "calendarDate", "date", "updatedDate", "from"):
         value = payload.get(key)
@@ -58,6 +109,25 @@ def remote_id(payload: dict[str, Any], fallback: str) -> str:
     return fallback
 
 
+# Scheduled workouts are tiny calendar payloads (one GET per month), so a year
+# of lookahead costs little next to a normal Garmin sync. Months back keep
+# recently completed schedules associatable with their finished activities.
+SCHEDULED_WORKOUTS_MONTHS_BACK = 3
+SCHEDULED_WORKOUTS_MONTHS_AHEAD = 12
+
+# Regular syncs reach back only far enough to associate recently finished
+# events with their activities; deeper history arrives via the automatic
+# coverage backfill (the parent passes --events-from when the store's own
+# window predates this span).
+EVENTS_PAST_DAYS = 30
+
+
+def shift_month(base: date, offset: int) -> date:
+    """Return the first day of the month `offset` months from `base`'s month."""
+    total = base.year * 12 + (base.month - 1) + offset
+    return date(total // 12, total % 12 + 1, 1)
+
+
 def payload_date(payload: Mapping[str, Any]) -> str | None:
     """Return the first ISO calendar day exposed by a Garmin payload."""
     for key in ("calendarDate", "date", "until", "from", "timestamp", "timestampLocal", "startTimestampGMT"):
@@ -80,11 +150,23 @@ def payload_date(payload: Mapping[str, Any]) -> str | None:
 class GarminStagingWorker:
     """Extract Garmin data through the explicit read-only registry into JSONL/Parquet staging."""
 
-    def __init__(self, api: Any, writer: StagingWriter, data_dir: Path, known_activity_hashes: Mapping[str, str] | None = None) -> None:
+    def __init__(self, api: Any, writer: StagingWriter, data_dir: Path, known_activity_hashes: Mapping[str, str] | None = None, progress: ProgressReporter | None = None) -> None:
         self.api = api
         self.writer = writer
         self.data_dir = data_dir
         self.known_activity_hashes = dict(known_activity_hashes or {})
+        self.progress = progress
+        self._interrupted = False
+
+    def request_interrupt(self) -> None:
+        """Ask the worker to stop at the next safe boundary."""
+        self._interrupted = True
+
+    def _check_interrupted(self) -> None:
+        if self._interrupted:
+            if self.progress is not None:
+                self.progress.finish("interrupted")
+            raise WorkerInterrupted("Sync run interrupted between extraction steps")
 
     def sync(
         self,
@@ -94,24 +176,43 @@ class GarminStagingWorker:
         daily_to_date: date | None = None,
         activity_to_date: date | None = None,
         include_non_historical: bool = True,
+        lactate_threshold_history_from: date | None = None,
+        events_from: str | None = None,
     ) -> None:
         assert_read_only_registry()
         end = to_date or date.today()
         daily_end = daily_to_date or end
         activity_end = activity_to_date or end
         if include_non_historical:
+            self._check_interrupted()
             self._singletons()
         if daily_from_date and daily_from_date <= daily_end:
+            self._check_interrupted()
             self._daily(daily_from_date, daily_end)
+            self._check_interrupted()
             self._range(daily_from_date, daily_end)
+            self._check_interrupted()
             self._cycling_ftp_history(daily_from_date, daily_end)
+            self._check_interrupted()
             self._max_metrics_history(daily_from_date, daily_end)
+            self._check_interrupted()
             self._hrv_history(daily_from_date, daily_end)
+            self._check_interrupted()
             self._score_history(daily_from_date, daily_end)
+        # Lactate-threshold history uses the widest requested window so a
+        # single sync can catch stores up that were created before per-day
+        # LT capture existed; runs even when the daily window is skipped.
+        lt_windows = [window for window in (daily_from_date, lactate_threshold_history_from) if window is not None]
+        lt_start = min(lt_windows) if lt_windows else None
+        if lt_start is not None and lt_start <= daily_end:
+            self._check_interrupted()
+            self._lactate_threshold_history(lt_start, daily_end)
         if activity_from_date and activity_from_date <= activity_end:
+            self._check_interrupted()
             self._activities(activity_from_date, activity_end)
         if include_non_historical:
-            self._collections()
+            self._check_interrupted()
+            self._collections(events_from=events_from)
 
     def _capture(self, endpoint: str, action: Callable[[], Any], remote_id_value: str | None = None, scope: dict[str, Any] | None = None) -> tuple[Any | None, str | None]:
         try:
@@ -162,10 +263,18 @@ class GarminStagingWorker:
             "golf_user_stats": ("get_golf_user_stats", "golf_user_stat"),
             "golf_club_stats": ("get_golf_club_stats", "golf_club_stat"),
         }
-        for endpoint, (method, entity_type) in calls.items():
+        if self.progress is not None:
+            self.progress.set_stage("singletons")
+            self.progress.advance(total=len(calls))
+        for index, (endpoint, (method, entity_type)) in enumerate(calls.items(), start=1):
+            self._check_interrupted()
+            if self.progress is not None:
+                self.progress.advance(step=endpoint)
             payload, raw_hash = self._capture(endpoint, lambda method=method: getattr(self.api, method)())
             if payload is not None:
                 self._entity(endpoint, entity_type, payload, raw_hash)
+            if self.progress is not None:
+                self.progress.advance(completed=index)
 
     def _daily(self, from_date: date, to_date: date) -> None:
         calls = {
@@ -183,13 +292,26 @@ class GarminStagingWorker:
             "nutrition_food_log": ("get_nutrition_daily_food_log", "nutrition_log"), "nutrition_meals": ("get_nutrition_daily_meals", "nutrition_log"),
             "nutrition_settings": ("get_nutrition_daily_settings", "nutrition_setting"),
         }
+        total_days = (to_date - from_date).days + 1
+        if self.progress is not None:
+            self.progress.set_stage("daily")
+            self.progress.advance(total=total_days)
         current = from_date
+        completed_days = 0
         while current <= to_date:
+            self._check_interrupted()
             day = current.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=day)
             for endpoint, (method, entity_type) in calls.items():
+                if self.progress is not None:
+                    self.progress.advance(step=f"{day} {endpoint}")
                 payload, raw_hash = self._capture(endpoint, lambda method=method, day=day: getattr(self.api, method)(day), day, {"date": day})
                 if payload is not None:
                     self._entity(endpoint, entity_type, payload, raw_hash, day)
+            completed_days += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_days)
             current += timedelta(days=1)
 
     def _range(self, from_date: date, to_date: date) -> None:
@@ -198,7 +320,10 @@ class GarminStagingWorker:
             "blood_pressure": ("get_blood_pressure", "blood_pressure"), "weigh_ins": ("get_weigh_ins", "body_composition"),
             "progress_summary": ("get_progress_summary_between_dates", "progress_summary"), "menstrual_calendar": ("get_menstrual_calendar_data", "menstrual"),
         }
-        for endpoint, (method, entity_type) in calls.items():
+        if self.progress is not None:
+            self.progress.set_stage("range")
+            self.progress.advance(total=len(calls))
+        for index, (endpoint, (method, entity_type)) in enumerate(calls.items(), start=1):
             # Garmin rejects broad body-battery and menstrual-calendar ranges.
             # Keep every request inside the provider's 92-day limit.
             window_start = from_date
@@ -206,23 +331,36 @@ class GarminStagingWorker:
             # ranges. Keep it deliberately small; the captures are
             # content-addressed so overlapping retry windows are harmless.
             window_days = 7 if endpoint == "body_battery" else (90 if endpoint == "menstrual_calendar" else (to_date - from_date).days + 1)
+            if self.progress is not None:
+                self.progress.advance(step=endpoint)
             while window_start <= to_date:
+                self._check_interrupted()
                 window_end = min(to_date, window_start + timedelta(days=window_days - 1))
                 start, end = window_start.isoformat(), window_end.isoformat()
                 payload, raw_hash = self._capture(endpoint, lambda method=method, start=start, end=end: getattr(self.api, method)(start, end), None, {"from": start, "to": end})
                 if payload is not None:
                     self._entity(endpoint, entity_type, payload, raw_hash, fallback_scope=start)
                 window_start = window_end + timedelta(days=1)
+            if self.progress is not None:
+                self.progress.advance(completed=index)
 
     def _cycling_ftp_history(self, from_date: date, to_date: date) -> None:
         """Stage daily cycling FTP setting history from Garmin's range endpoint."""
         endpoint = "functional_threshold_power_range"
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("ftp_history")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             # This private Connect endpoint is not documented with a maximum
             # range. Keep requests aligned with other conservative range calls.
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture(
                 endpoint,
                 lambda start=start, end=end: self.api.get_functional_threshold_power_range(
@@ -251,14 +389,60 @@ class GarminStagingWorker:
                         raw_hash,
                         occurred_on=occurred_on,
                     )
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
+            window_start = window_end + timedelta(days=1)
+
+    def _lactate_threshold_history(self, from_date: date, to_date: date) -> None:
+        """Stage daily running lactate-threshold history from Garmin's range endpoints."""
+        window_start = from_date
+        total_windows = (to_date - from_date).days // 365 + 1
+        if self.progress is not None:
+            self.progress.set_stage("lt_history")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
+        while window_start <= to_date:
+            self._check_interrupted()
+            # Garmin rejects range windows longer than 366 days.
+            window_end = min(to_date, window_start + timedelta(days=365))
+            start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
+            payload, raw_hash = self._capture(
+                "lactate_threshold_range",
+                lambda start=start, end=end: self.api.get_lactate_threshold(latest=False, start_date=start, end_date=end, aggregation="daily"),
+                None,
+                {"from": start, "to": end, "aggregation": "daily"},
+            )
+            if payload is not None and raw_hash is not None:
+                for item_day, threshold in lactate_threshold_days(payload).items():
+                    self.writer.source_entity(
+                        "lactate_threshold",
+                        f"daily:{item_day}",
+                        lactate_threshold_payload(item_day, threshold),
+                        raw_hash,
+                        occurred_on=item_day,
+                    )
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _max_metrics_history(self, from_date: date, to_date: date) -> None:
         """Stage range max-metric responses by their actual calendar date."""
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("max_metrics")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture(
                 "max_metrics_range",
                 lambda start=start, end=end: self.api.get_max_metrics_range(start, end),
@@ -286,14 +470,25 @@ class GarminStagingWorker:
                         for item in as_items(fallback):
                             self.writer.source_entity("max_metric", f"max_metrics:{day}", item, fallback_hash, occurred_on=day)
                 current += timedelta(days=1)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _hrv_history(self, from_date: date, to_date: date) -> None:
         """Stage the PR-402 HRV range API, retaining daily fallback coverage."""
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("hrv_history")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture(
                 "hrv_range",
                 lambda start=start, end=end: self.api.get_hrv_data_range(start, end),
@@ -315,14 +510,25 @@ class GarminStagingWorker:
                     if fallback is not None:
                         self.writer.source_entity("daily_health", f"hrv:{day}", as_dict(fallback), fallback_hash, occurred_on=day)
                 current += timedelta(days=1)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _score_history(self, from_date: date, to_date: date) -> None:
         """Stage daily-capable endurance-adjacent metrics from range endpoints."""
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("scores")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             for endpoint, method, entity_type in (
                 ("hill_score", lambda: self.api.get_hill_score(start, end), "hill_score"),
                 ("running_tolerance", lambda: self.api.get_running_tolerance(start, end, aggregation="daily"), "running_tolerance"),
@@ -333,33 +539,56 @@ class GarminStagingWorker:
                         item_day = payload_date(item)
                         if item_day:
                             self.writer.source_entity(entity_type, f"{endpoint}:{item_day}:{index}", item, raw_hash, occurred_on=item_day)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
         # Garmin limits daily race-prediction windows to one year.
         window_start = from_date
+        total_windows = (to_date - from_date).days // 365 + 1
+        if self.progress is not None:
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=365))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture("race_predictions", lambda start=start, end=end: self.api.get_race_predictions(start, end, "daily"), None, {"from": start, "to": end, "aggregation": "daily"})
             if payload is not None:
                 for index, item in enumerate(as_items(payload)):
                     item_day = payload_date(item) or start
                     self.writer.source_entity("race_prediction", f"race_prediction:{item_day}:{index}", item, raw_hash, occurred_on=item_day)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _activities(self, from_date: date, to_date: date) -> None:
         start, end = from_date.isoformat(), to_date.isoformat()
+        if self.progress is not None:
+            self.progress.set_stage("activities")
         payload, raw_hash = self._capture("activities", lambda: self.api.get_activities_by_date(start, end), None, {"from": start, "to": end})
         if payload is None:
             return
         self._entity("activities", "activity", payload, raw_hash)
-        for summary in as_items(payload):
+        summaries = as_items(payload)
+        if self.progress is not None:
+            self.progress.advance(total=len(summaries))
+        for index, summary in enumerate(summaries, start=1):
+            self._check_interrupted()
             activity_id = remote_id(summary, "unknown")
+            if self.progress is not None:
+                self.progress.advance(step=activity_id)
             summary_hash = hashlib.sha256(json.dumps(summary, sort_keys=True, separators=(",", ":"), default=str).encode()).hexdigest()
             details_fetched = self.known_activity_hashes.get(activity_id) != summary_hash
             if details_fetched:
                 self._activity_details(activity_id, summary)
             self.writer.activity_sync_state(activity_id, summary_hash, details_fetched)
+            if self.progress is not None:
+                self.progress.advance(completed=index)
 
     def _multisport_children(self, parent_activity_id: str, activity: dict[str, Any]) -> None:
         if not activity.get("isMultiSportParent"):
@@ -373,6 +602,49 @@ class GarminStagingWorker:
             if isinstance(payload, dict):
                 self.writer.source_entity("activity", child_id, payload, raw_hash, parent_remote_id=parent_activity_id)
 
+    def _is_swim_activity(self, summary: dict[str, Any], activity: dict[str, Any] | None, details: dict[str, Any] | None) -> bool:
+        """Return True when any of the Garmin sport/type fields indicates a swim."""
+        candidates: list[str] = []
+        # Direct sport string fields on the list summary (including flat activityType string).
+        for key in ("sport", "sportType", "sport_type", "activityType", "activityTypeKey"):
+            value = summary.get(key)
+            if isinstance(value, str) and value:
+                candidates.append(value)
+        # Nested activityType shapes on the list summary.
+        for key in ("activityType", "activityTypeDTO"):
+            nested = summary.get(key)
+            if isinstance(nested, dict):
+                type_key = nested.get("typeKey") or nested.get("type_key") or nested.get("type") or nested.get("key")
+                if isinstance(type_key, str) and type_key:
+                    candidates.append(type_key)
+        # Detailed payloads provide the authoritative typeKey.
+        for payload in (activity, details):
+            if not isinstance(payload, dict):
+                continue
+            for key in ("activityType", "activityTypeDTO"):
+                nested = payload.get(key)
+                if isinstance(nested, dict):
+                    type_key = nested.get("typeKey")
+                    if isinstance(type_key, str) and type_key:
+                        candidates.append(type_key)
+            for key in ("sport", "sportType"):
+                value = payload.get(key)
+                if isinstance(value, str) and value:
+                    candidates.append(value)
+            summary_dto = payload.get("summaryDTO")
+            if isinstance(summary_dto, dict):
+                for key in ("activityType", "activityTypeDTO"):
+                    nested = summary_dto.get(key)
+                    if isinstance(nested, dict):
+                        type_key = nested.get("typeKey")
+                        if isinstance(type_key, str) and type_key:
+                            candidates.append(type_key)
+        for candidate in candidates:
+            lowered = candidate.lower()
+            if lowered == "lap_swimming" or "swim" in lowered:
+                return True
+        return False
+
     def _activity_details(self, activity_id: str, summary: dict[str, Any]) -> None:
         calls = {
             "activity": ("get_activity", "activity_detail"), "activity_details": ("get_activity_details", "activity_detail"),
@@ -382,17 +654,19 @@ class GarminStagingWorker:
             "activity_exercise_sets": ("get_activity_exercise_sets", "activity_exercise_set"), "activity_gear": ("get_activity_gear", "activity_gear"),
         }
         details: dict[str, Any] | None = None
+        activity_payload: dict[str, Any] | None = None
         for endpoint, (method, entity_type) in calls.items():
             payload, raw_hash = self._capture(endpoint, lambda method=method: getattr(self.api, method)(activity_id), activity_id)
             if payload is not None:
                 self._entity(endpoint, entity_type, payload, raw_hash, parent_remote_id=activity_id)
                 if endpoint == "activity" and isinstance(payload, dict):
+                    activity_payload = payload
                     self._multisport_children(activity_id, payload)
                 if endpoint == "activity_details" and isinstance(payload, dict):
                     details = payload
-        self._activity_files(activity_id, summary, details)
+        self._activity_files(activity_id, summary, activity_payload, details)
 
-    def _activity_files(self, activity_id: str, summary: dict[str, Any], details: dict[str, Any] | None) -> None:
+    def _activity_files(self, activity_id: str, summary: dict[str, Any], activity: dict[str, Any] | None, details: dict[str, Any] | None) -> None:
         try:
             from garminconnect import Garmin
             formats = {
@@ -437,14 +711,101 @@ class GarminStagingWorker:
                     parent_remote_id=activity_id,
                     occurred_on=start_date[:10],
                 )
+        if original_path and original_path.exists():
+            if self._is_swim_activity(summary, activity, details):
+                lengths = fit_archive_to_swim_lengths(f"garmin:{activity_id}", original_path)
+                if lengths:
+                    start_date = str(summary.get("startTimeLocal") or summary.get("startTimeGMT") or date.today().isoformat())
+                    self.writer.source_entity(
+                        "activity_swim_lengths",
+                        f"{activity_id}:fit",
+                        {"lengths": lengths},
+                        original_hash,
+                        parent_remote_id=activity_id,
+                        occurred_on=start_date[:10],
+                    )
 
-    def _collections(self) -> None:
+    def _fetch_garmin_events(self, start_date: str) -> None:
+        """Fetch calendar events from start_date, following pagination."""
+        page = 1
+        while True:
+            payload, raw_hash = self._capture(
+                "garmin_events",
+                lambda page=page: self.api.get_events(start_date, limit=100, page=page),
+                scope={"startDate": start_date, "page": page},
+            )
+            items = payload if isinstance(payload, list) else []
+            if items:
+                self._entity("garmin_events", "event", items, raw_hash)
+            if len(items) < 100:
+                return
+            page += 1
+
+    def _collections(self, events_from: str | None = None) -> None:
         today = date.today()
         calls = {
-            "workouts": ("get_workouts", (), "workout"), "scheduled_workouts": ("get_scheduled_workouts", (today.year, today.month), "scheduled_workout"),
+            "workouts": ("get_workouts", (), "workout"),
             "goals": ("get_goals", (), "goal"), "golf_summary": ("get_golf_summary", (), "golf_scorecard"),
         }
-        for endpoint, (method, arguments, entity_type) in calls.items():
+        months = [shift_month(today, offset) for offset in range(-SCHEDULED_WORKOUTS_MONTHS_BACK, SCHEDULED_WORKOUTS_MONTHS_AHEAD + 1)]
+        events_start = events_from or (today - timedelta(days=EVENTS_PAST_DAYS)).isoformat()
+        if self.progress is not None:
+            self.progress.set_stage("collections")
+            self.progress.advance(total=len(calls) + len(months) + 1)
+        for index, (endpoint, (method, arguments, entity_type)) in enumerate(calls.items(), start=1):
+            self._check_interrupted()
+            if self.progress is not None:
+                self.progress.advance(step=endpoint)
             payload, raw_hash = self._capture(endpoint, lambda method=method, arguments=arguments: getattr(self.api, method)(*arguments))
             if payload is not None:
                 self._entity(endpoint, entity_type, payload, raw_hash)
+            if self.progress is not None:
+                self.progress.advance(completed=index)
+        # Scheduled workouts span past-to-future months so upcoming sessions
+        # surface ahead of time and recently completed ones stay associatable
+        # with their finished activities. The calendar service answers each
+        # month with a grid wrapper whose items live under `calendarItems`;
+        # empty months must stage nothing, and real items stage one row each
+        # with their own calendar date.
+        for month_index, month in enumerate(months, start=1):
+            self._check_interrupted()
+            payload, raw_hash = self._capture(
+                "scheduled_workouts",
+                lambda month=month: self.api.get_scheduled_workouts(month.year, month.month),
+                scope={"month": month.isoformat()},
+            )
+            items = payload.get("calendarItems") if isinstance(payload, Mapping) else payload
+            # itemType 'activity' entries are echoes of already-recorded
+            # activities (the activities endpoint owns those); only true
+            # scheduled workout templates belong in this entity family.
+            if items:
+                items = [item for item in items if isinstance(item, Mapping) and item.get("itemType") == "workout"]
+            if items:
+                self._entity("scheduled_workouts", "scheduled_workout", items, raw_hash)
+            if self.progress is not None:
+                self.progress.advance(completed=len(calls) + month_index)
+        # Joined events (races etc.) look back only far enough to associate
+        # finished activities; the parent widens start_date into a one-time
+        # coverage backfill when the store predates this span.
+        self._check_interrupted()
+        if self.progress is not None:
+            self.progress.advance(step="garmin_events")
+        self._fetch_garmin_events(events_start)
+        if self.progress is not None:
+            self.progress.advance(completed=len(calls) + len(months) + 1)
+
+    def _fetch_garmin_events(self, start_date: str) -> None:
+        """Fetch calendar events from start_date, following pagination."""
+        page = 1
+        while True:
+            payload, raw_hash = self._capture(
+                "garmin_events",
+                lambda page=page: self.api.get_events(start_date, limit=100, page=page),
+                scope={"startDate": start_date, "page": page},
+            )
+            items = payload if isinstance(payload, list) else []
+            if items:
+                self._entity("garmin_events", "event", items, raw_hash)
+            if len(items) < 100:
+                return
+            page += 1