kriss/geniusrun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add implementation plan for permanently-missing-workout handling

Browse Source 
4 tasks: mark a wrapper-level 404 as not_found, expose it as
garmin.ErrNotFound in the Go client, add a workout_not_found_at
column + store query updates, then have fillPendingWorkouts stop
retrying a confirmed-404 workout instead of retrying forever.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Kriss Vila
2026-07-27 18:45:11 +02:00
parent 67f4ec27ab
commit b5cd47c219
1 changed files with 844 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

844
docs/superpowers/plans/2026-07-27-workout-not-found-plan.md Normal file
View File

@@ -0,0 +1,844 @@
# Stop Retrying a Permanently-Missing Garmin Workout Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Stop `fillPendingWorkouts` from retrying a `get_workout_by_id` call forever when Garmin
returns a definitive 404 (the workout was deleted after being linked to an activity), per
`docs/superpowers/specs/2026-07-27-workout-not-found-design.md`.
**Architecture:** `garminconnect`'s own `GarminConnectNotFoundError` (raised for any HTTP 404) is
caught specifically in `wrapper.py`'s dispatch loop and marked with `"not_found": true` in the
JSON error response. `internal/garmin/client.go` turns that into a Go sentinel error
(`ErrNotFound`) any caller can `errors.Is` against. `internal/sync/service.go`'s
`fillPendingWorkouts` checks for it and, only for that specific case, calls a new store method
(`SetActivityWorkoutNotFound`) that permanently excludes the activity from
`ActivitiesMissingWorkout`/`CountActivitiesMissingWorkout` -- `workout_raw_json` stays `NULL`
forever (no fabricated data), but a new `workout_not_found_at` column distinguishes "confirmed
missing" from "not yet fetched."
**Tech Stack:** Go (backend, `internal/garmin`/`internal/store`/`internal/sync`), Python
(`internal/garmin/pyscript/wrapper.py`). No frontend changes.
## Global Constraints
- `gofmt -l .` must report nothing; `go build ./...`, `go vet ./...`, `go test ./...` must all
pass before any commit.
- Every store method takes an explicit `userID` and uses it in a real `WHERE`/`JOIN` clause (per
this repo's per-user isolation convention) -- `SetActivityWorkoutNotFound` follows the exact
pattern of the existing `SetActivitySplitsFetched`.
- No migration history: `internal/store/schema.sql` is edited directly, then
`go run ./cmd/dumpschema` regenerates `docs/DATABASE.md`.
- `fillActivityDetails`/`fillPendingActivityDetails`'s error handling (abort-the-batch-and-report)
is explicitly out of scope -- this fix only changes `fillPendingWorkouts`'s behavior.
- No frontend changes -- `workouts_pending` simply stops counting a confirmed-missing workout.
---
### Task 1: `wrapper.py` marks a 404 with `not_found: true`
**Files:**
- Modify: `backend/internal/garmin/pyscript/wrapper.py` (imports, `dispatch`)
- Modify: `backend/internal/garmin/pyscript/tests/test_wrapper.py` (new test)
**Interfaces:**
- Consumes: `garminconnect.GarminConnectNotFoundError` (already installed as a dependency).
- Produces: `dispatch()`'s returned error dict gains an additional `"not_found": true` key
whenever the caught exception is (or is a subclass of) `GarminConnectNotFoundError` -- Task 2
reads this field on the Go side.
- [ ] **Step 1: Write the failing test**
Add to `backend/internal/garmin/pyscript/tests/test_wrapper.py`:
```python
def test_call_marks_not_found_error_specifically():
from garminconnect import GarminConnectNotFoundError
wrapper._auth_state = "authenticated"
wrapper._client = MagicMock()
wrapper._client.get_workout_by_id.side_effect = GarminConnectNotFoundError("API Error 404")
resp = wrapper.dispatch({
"id": 11, "cmd": "call", "params": {"method": "get_workout_by_id", "args": {"workout_id": "999"}},
})
assert resp == {"id": 11, "error": "API Error 404", "not_found": True}
def test_call_does_not_mark_other_errors_as_not_found():
wrapper._auth_state = "authenticated"
wrapper._client = MagicMock()
wrapper._client.get_workout_by_id.side_effect = Exception("rate limited")
resp = wrapper.dispatch({
"id": 12, "cmd": "call", "params": {"method": "get_workout_by_id", "args": {"workout_id": "999"}},
})
assert resp == {"id": 12, "error": "rate limited"}
```
- [ ] **Step 2: Run it to verify it fails**
Run: `cd backend/internal/garmin/pyscript && python3 -m pytest tests/test_wrapper.py -k not_found -v`
(use whatever Python interpreter this repo's wrapper tests normally run under -- see
`backend/internal/garmin/pyscript/.venv` if one exists, or the `GARMIN_WRAPPER_PYTHON` convention).
Expected: `test_call_marks_not_found_error_specifically` FAILS (`resp` has no `"not_found"` key
yet); `test_call_does_not_mark_other_errors_as_not_found` already passes (nothing to change for
that case).
- [ ] **Step 3: Update `dispatch()`**
In `backend/internal/garmin/pyscript/wrapper.py`, replace:
```python
from garminconnect import Garmin
```
with:
```python
from garminconnect import Garmin, GarminConnectNotFoundError
```
Replace:
```python
def dispatch(req):
handler = _HANDLERS.get(req.get("cmd"))
if handler is None:
return {"id": req.get("id"), "error": f"unknown cmd {req.get('cmd')!r}"}
try:
result = handler(req.get("params") or {})
return {"id": req["id"], "result": result}
except Exception as exc:
_debug(f"{req.get('cmd')} raised {type(exc).__name__}: {exc}")
_debug(traceback.format_exc())
return {"id": req.get("id"), "error": str(exc)}
```
with:
```python
def dispatch(req):
handler = _HANDLERS.get(req.get("cmd"))
if handler is None:
return {"id": req.get("id"), "error": f"unknown cmd {req.get('cmd')!r}"}
try:
result = handler(req.get("params") or {})
return {"id": req["id"], "result": result}
except Exception as exc:
_debug(f"{req.get('cmd')} raised {type(exc).__name__}: {exc}")
_debug(traceback.format_exc())
resp = {"id": req.get("id"), "error": str(exc)}
# A 404 (e.g. get_workout_by_id for a workout deleted on Garmin's
# side after being linked to an activity) is definitive, not a
# transient failure worth retrying forever -- marked specifically so
# internal/garmin/client.go can tell the two apart (see
# docs/superpowers/specs/2026-07-27-workout-not-found-design.md).
if isinstance(exc, GarminConnectNotFoundError):
resp["not_found"] = True
return resp
```
- [ ] **Step 4: Run the test to verify it passes**
Run: `cd backend/internal/garmin/pyscript && python3 -m pytest tests/test_wrapper.py -v`
Expected: all tests PASS, including both new ones and every existing test unchanged.
- [ ] **Step 5: Commit**
```bash
git add backend/internal/garmin/pyscript/wrapper.py backend/internal/garmin/pyscript/tests/test_wrapper.py
git commit -m "$(cat <<'EOF'
feat(garmin): mark a wrapper 404 with not_found in the error response
garminconnect's own GarminConnectNotFoundError already exists
specifically for this (its docstring: "so callers can now catch a
missing resource specifically, e.g. deleting an already-deleted
workout"), raised by connectapi() for any real HTTP 404. dispatch()
now surfaces that distinction as an extra not_found: true field
alongside the existing error string, so internal/garmin/client.go
(next commit) can tell a definitive 404 apart from a transient
failure.
EOF
)"
```
---
### Task 2: `internal/garmin/client.go` exposes `ErrNotFound`
**Files:**
- Modify: `backend/internal/garmin/client.go` (`wireResponse`, new `ErrNotFound`, `roundTrip`)
- Modify: `backend/internal/garmin/client_test.go` (`wireResponsePayload`/harness, new test)
**Interfaces:**
- Consumes: `wireResponse.NotFound` (wire field written by Task 1's `wrapper.py` change).
- Produces: `var ErrNotFound error` -- Task 4 (`fillPendingWorkouts`) checks
`errors.Is(err, garmin.ErrNotFound)` against errors returned by `GetWorkoutByID` (and, since
this is wired at the generic `roundTrip` level, any other `Client` method too).
- [ ] **Step 1: Write the failing test**
Add to `backend/internal/garmin/client_test.go`, right after `fakeError`:
```go
func fakeNotFoundError(msg string) wireResponsePayload {
return wireResponsePayload{err: msg, notFound: true}
}
```
Update the `wireResponsePayload` struct (near the top of the file) from:
```go
type wireResponsePayload struct {
result json.RawMessage
err string
}
```
to:
```go
type wireResponsePayload struct {
result json.RawMessage
err string
notFound bool
}
```
Update `newFakeWrapperClient`'s harness -- replace:
```go
payload := handle(req.Cmd, req.Params)
resp := wireResponse{ID: req.ID, Result: payload.result, Error: payload.err}
```
with:
```go
payload := handle(req.Cmd, req.Params)
resp := wireResponse{ID: req.ID, Result: payload.result, Error: payload.err, NotFound: payload.notFound}
```
Add a new test, right after `TestSubprocessClient_RoundTrip_WrapperErrorPropagates`:
```go
func TestSubprocessClient_RoundTrip_NotFoundWrapsErrNotFound(t *testing.T) {
c := newFakeWrapperClient(t, func(cmd string, params json.RawMessage) wireResponsePayload {
return fakeNotFoundError("API Error 404")
})
_, err := c.roundTrip(context.Background(), "call", nil)
if !errors.Is(err, ErrNotFound) {
t.Fatalf("roundTrip error = %v, want errors.Is(err, ErrNotFound)", err)
}
if !strings.Contains(err.Error(), "API Error 404") {
t.Errorf("roundTrip error = %v, want it to still contain the original message", err)
}
}
func TestSubprocessClient_RoundTrip_OrdinaryErrorDoesNotWrapErrNotFound(t *testing.T) {
c := newFakeWrapperClient(t, func(cmd string, params json.RawMessage) wireResponsePayload {
return fakeError("boom")
})
_, err := c.roundTrip(context.Background(), "call", nil)
if errors.Is(err, ErrNotFound) {
t.Fatalf("roundTrip error = %v, want errors.Is(err, ErrNotFound) to be false", err)
}
}
```
Add `"errors"` to this file's import block (alongside the existing `"strings"` etc.).
- [ ] **Step 2: Run it to verify it fails**
Run: `cd backend && go test ./internal/garmin/... -run TestSubprocessClient_RoundTrip_NotFound -v`
Expected: FAIL to compile (`wireResponsePayload` has no field `notFound` yet -- wait, Step 1 above
already added it to the test file; the actual compile failure is `wireResponse` has no field
`NotFound` yet, and `ErrNotFound` is undefined) -- confirms the test exercises code that doesn't
exist yet.
- [ ] **Step 3: Add `ErrNotFound` and wire it through `roundTrip`**
In `backend/internal/garmin/client.go`, replace:
```go
// wireResponse is one line read from the wrapper subprocess's stdout.
type wireResponse struct {
ID int `json:"id"`
Result json.RawMessage `json:"result,omitempty"`
Error string `json:"error,omitempty"`
}
```
with:
```go
// wireResponse is one line read from the wrapper subprocess's stdout.
type wireResponse struct {
ID int `json:"id"`
Result json.RawMessage `json:"result,omitempty"`
Error string `json:"error,omitempty"`
NotFound bool `json:"not_found,omitempty"`
}
// ErrNotFound wraps any error a Client method returns when the wrapper
// reported a definitive HTTP 404 (garminconnect's own
// GarminConnectNotFoundError) -- e.g. GetWorkoutByID for a workout deleted
// on Garmin's side after being linked to an activity. Callers use
// errors.Is(err, ErrNotFound) to distinguish this from a transient failure
// worth retrying.
var ErrNotFound = errors.New("garmin: resource not found")
```
Replace, in `roundTrip`:
```go
if resp.Error != "" {
err = fmt.Errorf("%s: %s", cmdName, resp.Error)
return nil, err
}
```
with:
```go
if resp.Error != "" {
if resp.NotFound {
err = fmt.Errorf("%s: %s: %w", cmdName, resp.Error, ErrNotFound)
} else {
err = fmt.Errorf("%s: %s", cmdName, resp.Error)
}
return nil, err
}
```
Add `"errors"` to `client.go`'s import block.
- [ ] **Step 4: Run the test to verify it passes**
Run: `cd backend && go test ./internal/garmin/... -v`
Expected: all tests PASS, including the two new ones and every existing test unchanged.
- [ ] **Step 5: Run the full backend suite**
Run: `cd backend && go build ./... && go vet ./... && gofmt -l . && go test ./...`
Expected: all pass, `gofmt -l .` prints nothing.
- [ ] **Step 6: Commit**
```bash
git add backend/internal/garmin/client.go backend/internal/garmin/client_test.go
git commit -m "$(cat <<'EOF'
feat(garmin): expose ErrNotFound for a wrapper-reported 404
roundTrip now wraps the returned error with the new ErrNotFound
sentinel whenever the wrapper's response set not_found (Task 1),
letting any Client method's caller distinguish a definitive 404 from
a transient failure via errors.Is, regardless of which garminconnect
method was called.
EOF
)"
```
---
### Task 3: Store gains `workout_not_found_at`
**Files:**
- Modify: `backend/internal/store/schema.sql` (`activities` table)
- Modify: `backend/internal/store/activities.go` (`Activity` struct, `activityColumns`,
`scanActivity`, new `SetActivityWorkoutNotFound`, `ActivitiesMissingWorkout`/
`CountActivitiesMissingWorkout`)
- Modify: `backend/internal/store/store_test.go` (extend the existing test, add a new one)
- Regenerate: `docs/DATABASE.md` (via `go run ./cmd/dumpschema`)
**Interfaces:**
- Consumes: nothing new.
- Produces: `db.SetActivityWorkoutNotFound(ctx, userID, activityID int64) error` -- Task 4
(`fillPendingWorkouts`) calls this. `Activity.WorkoutNotFoundAt *string` -- available to any
caller of `GetActivity`/`ListActivities`/etc. that wants to check it (none currently do, besides
this task's own test).
- [ ] **Step 1: Write the failing test**
Add to `backend/internal/store/store_test.go`, a new test (don't modify the existing
`TestActivitiesMissingWorkout_OnlyIncludesActivitiesWithDetailsAlreadyFetched` -- this is
additive):
```go
func TestActivitiesMissingWorkout_ExcludesConfirmedNotFound(t *testing.T) {
db := openTestDB(t)
ctx := context.Background()
userID, err := db.ProvisionUser(ctx, "test-sub", "Test")
if err != nil {
t.Fatalf("ProvisionUser: %v", err)
}
workoutID := int64(999)
// Details already fetched, workout confirmed 404 on Garmin -- must not
// be retried, so must not appear in ActivitiesMissingWorkout/Count.
notFound := Activity{
GarminActivityID: 1, WorkoutID: &workoutID,
StartTimeUTC: "2026-07-01 06:00:00", RawJSON: "{}",
}
idA, err := db.UpsertActivity(ctx, userID, notFound)
if err != nil {
t.Fatalf("UpsertActivity (a): %v", err)
}
if err := db.SetActivityDetails(ctx, userID, idA, "{}"); err != nil {
t.Fatalf("SetActivityDetails (a): %v", err)
}
if err := db.SetActivitySplitsFetched(ctx, userID, idA); err != nil {
t.Fatalf("SetActivitySplitsFetched (a): %v", err)
}
if err := db.SetActivityWorkoutNotFound(ctx, userID, idA); err != nil {
t.Fatalf("SetActivityWorkoutNotFound (a): %v", err)
}
// A genuinely still-pending activity (details fetched, workout not yet
// attempted) must still be included, for contrast.
stillPending := Activity{
GarminActivityID: 2, WorkoutID: &workoutID,
StartTimeUTC: "2026-07-02 06:00:00", RawJSON: "{}",
}
idB, err := db.UpsertActivity(ctx, userID, stillPending)
if err != nil {
t.Fatalf("UpsertActivity (b): %v", err)
}
if err := db.SetActivityDetails(ctx, userID, idB, "{}"); err != nil {
t.Fatalf("SetActivityDetails (b): %v", err)
}
if err := db.SetActivitySplitsFetched(ctx, userID, idB); err != nil {
t.Fatalf("SetActivitySplitsFetched (b): %v", err)
}
n, err := db.CountActivitiesMissingWorkout(ctx, userID)
if err != nil {
t.Fatalf("CountActivitiesMissingWorkout: %v", err)
}
if n != 1 {
t.Fatalf("CountActivitiesMissingWorkout = %d, want 1 (only activity b)", n)
}
pending, err := db.ActivitiesMissingWorkout(ctx, userID, 10)
if err != nil {
t.Fatalf("ActivitiesMissingWorkout: %v", err)
}
if len(pending) != 1 || pending[0].ID != idB {
t.Fatalf("ActivitiesMissingWorkout = %+v, want only activity b (id %d)", pending, idB)
}
confirmed, _, err := db.GetActivity(ctx, userID, idA)
if err != nil {
t.Fatalf("GetActivity (a): %v", err)
}
if confirmed.WorkoutNotFoundAt == nil {
t.Error("activity a's WorkoutNotFoundAt is nil, want it set")
}
if confirmed.WorkoutRawJSON != nil {
t.Error("activity a's WorkoutRawJSON should stay nil -- not-found is recorded separately, not faked")
}
}
```
- [ ] **Step 2: Run it to verify it fails**
Run: `cd backend && go test ./internal/store/... -run TestActivitiesMissingWorkout_ExcludesConfirmedNotFound -v`
Expected: FAIL to compile (`db.SetActivityWorkoutNotFound` and `Activity.WorkoutNotFoundAt`
undefined).
- [ ] **Step 3: Add the schema column**
In `backend/internal/store/schema.sql`, replace:
```sql
-- Genuine raw get_workout_by_id() response, the source used to compute
-- alignWorkoutTargets. Null when the activity has no workout_id.
workout_raw_json TEXT,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
```
with:
```sql
-- Genuine raw get_workout_by_id() response, the source used to compute
-- alignWorkoutTargets. Null when the activity has no workout_id.
workout_raw_json TEXT,
-- Set when get_workout_by_id returned a definitive HTTP 404 (the
-- workout was deleted on Garmin's side after being linked to this
-- activity) -- distinct from workout_raw_json staying null for "not yet
-- fetched": this activity is excluded from ActivitiesMissingWorkout so
-- it stops being retried forever (see
-- docs/superpowers/specs/2026-07-27-workout-not-found-design.md).
-- workout_raw_json itself is never fabricated; it just stays null.
workout_not_found_at TEXT,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
```
- [ ] **Step 4: Update the Go struct, column list, and scan**
In `backend/internal/store/activities.go`, replace:
```go
// WorkoutRawJSON is the genuine raw get_workout_by_id() response for this
// activity's structured workout -- the source used to compute each lap's
// TargetPaceLowMps/HighMps and TargetHRLowBpm/HighBpm (see
// internal/sync/mapping.go's alignWorkoutTargets). Nil when the activity
// has no WorkoutID, or was synced before this column existed.
WorkoutRawJSON *string
CreatedAt string
UpdatedAt string
}
```
with:
```go
// WorkoutRawJSON is the genuine raw get_workout_by_id() response for this
// activity's structured workout -- the source used to compute each lap's
// TargetPaceLowMps/HighMps and TargetHRLowBpm/HighBpm (see
// internal/sync/mapping.go's alignWorkoutTargets). Nil when the activity
// has no WorkoutID, or was synced before this column existed.
WorkoutRawJSON *string
// WorkoutNotFoundAt is set when get_workout_by_id returned a definitive
// HTTP 404 for this activity's WorkoutID -- distinct from
// WorkoutRawJSON staying nil for "not yet fetched" (see
// SetActivityWorkoutNotFound).
WorkoutNotFoundAt *string
CreatedAt string
UpdatedAt string
}
```
Replace:
```go
func scanActivity(row interface{ Scan(...any) error }) (Activity, error) {
var a Activity
err := row.Scan(
&a.ID, &a.GarminActivityID, &a.EventTypeKey, &a.WorkoutID, &a.StartTimeUTC,
&a.DurationSeconds, &a.DistanceMeters, &a.AvgHR, &a.MaxHR,
&a.AvgSpeedMps, &a.ElevationGainM,
&a.AerobicTrainingEffect, &a.AnaerobicTrainingEffect, &a.VO2MaxValue,
&a.RawJSON, &a.DetailsFetchedAt, &a.DetailsRawJSON, &a.SplitsFetchedAt, &a.WorkoutRawJSON,
&a.CreatedAt, &a.UpdatedAt,
)
return a, err
}
const activityColumns = `
id, garmin_activity_id, event_type_key, workout_id, start_time_utc,
duration_seconds, distance_meters, avg_hr, max_hr,
avg_speed_mps, elevation_gain_m,
aerobic_training_effect, anaerobic_training_effect, vo2max_value,
raw_json, details_fetched_at, details_raw_json, splits_fetched_at, workout_raw_json,
created_at, updated_at
`
```
with:
```go
func scanActivity(row interface{ Scan(...any) error }) (Activity, error) {
var a Activity
err := row.Scan(
&a.ID, &a.GarminActivityID, &a.EventTypeKey, &a.WorkoutID, &a.StartTimeUTC,
&a.DurationSeconds, &a.DistanceMeters, &a.AvgHR, &a.MaxHR,
&a.AvgSpeedMps, &a.ElevationGainM,
&a.AerobicTrainingEffect, &a.AnaerobicTrainingEffect, &a.VO2MaxValue,
&a.RawJSON, &a.DetailsFetchedAt, &a.DetailsRawJSON, &a.SplitsFetchedAt, &a.WorkoutRawJSON,
&a.WorkoutNotFoundAt, &a.CreatedAt, &a.UpdatedAt,
)
return a, err
}
const activityColumns = `
id, garmin_activity_id, event_type_key, workout_id, start_time_utc,
duration_seconds, distance_meters, avg_hr, max_hr,
avg_speed_mps, elevation_gain_m,
aerobic_training_effect, anaerobic_training_effect, vo2max_value,
raw_json, details_fetched_at, details_raw_json, splits_fetched_at, workout_raw_json,
workout_not_found_at, created_at, updated_at
`
```
- [ ] **Step 5: Add `SetActivityWorkoutNotFound` and update the two query methods**
In `backend/internal/store/activities.go`, right after `SetActivityWorkout`, add:
```go
// SetActivityWorkoutNotFound records that get_workout_by_id returned a
// definitive HTTP 404 for this activity's WorkoutID -- the workout was
// deleted on Garmin's side after being linked to this activity.
// WorkoutRawJSON is deliberately left nil (never fabricated); this is a
// separate marker so ActivitiesMissingWorkout stops retrying it forever.
func (db *DB) SetActivityWorkoutNotFound(ctx context.Context, userID, activityID int64) error {
_, err := db.ExecContext(ctx, `
UPDATE activities SET workout_not_found_at = datetime('now'), updated_at = datetime('now')
WHERE id = ? AND user_id = ?`, activityID, userID)
if err != nil {
return fmt.Errorf("set activity %d workout not found for user %d: %w", activityID, userID, err)
}
return nil
}
```
Replace:
```go
func (db *DB) ActivitiesMissingWorkout(ctx context.Context, userID int64, limit int) ([]Activity, error) {
rows, err := db.QueryContext(ctx, `SELECT `+activityColumns+` FROM activities
WHERE user_id = ? AND workout_id IS NOT NULL AND workout_raw_json IS NULL AND details_fetched_at IS NOT NULL
ORDER BY start_time_utc DESC LIMIT ?`, userID, limit)
```
with:
```go
func (db *DB) ActivitiesMissingWorkout(ctx context.Context, userID int64, limit int) ([]Activity, error) {
rows, err := db.QueryContext(ctx, `SELECT `+activityColumns+` FROM activities
WHERE user_id = ? AND workout_id IS NOT NULL AND workout_raw_json IS NULL
AND details_fetched_at IS NOT NULL AND workout_not_found_at IS NULL
ORDER BY start_time_utc DESC LIMIT ?`, userID, limit)
```
Replace:
```go
func (db *DB) CountActivitiesMissingWorkout(ctx context.Context, userID int64) (int, error) {
var n int
err := db.QueryRowContext(ctx, `SELECT COUNT(*) FROM activities
WHERE user_id = ? AND workout_id IS NOT NULL AND workout_raw_json IS NULL AND details_fetched_at IS NOT NULL`, userID).Scan(&n)
```
with:
```go
func (db *DB) CountActivitiesMissingWorkout(ctx context.Context, userID int64) (int, error) {
var n int
err := db.QueryRowContext(ctx, `SELECT COUNT(*) FROM activities
WHERE user_id = ? AND workout_id IS NOT NULL AND workout_raw_json IS NULL
AND details_fetched_at IS NOT NULL AND workout_not_found_at IS NULL`, userID).Scan(&n)
```
- [ ] **Step 6: Run the test to verify it passes**
Run: `cd backend && go test ./internal/store/... -run TestActivitiesMissingWorkout -v`
Expected: PASS, including both the existing test and the new one.
- [ ] **Step 7: Regenerate the schema doc**
Run: `cd backend && go run ./cmd/dumpschema`
Expected: `docs/DATABASE.md` updates to include `workout_not_found_at` in the `activities` table.
- [ ] **Step 8: Run the full backend suite**
Run: `cd backend && go build ./... && go vet ./... && gofmt -l . && go test ./...`
Expected: all pass, `gofmt -l .` prints nothing.
- [ ] **Step 9: Commit**
```bash
git add backend/internal/store/schema.sql backend/internal/store/activities.go backend/internal/store/store_test.go docs/DATABASE.md
git commit -m "$(cat <<'EOF'
feat(store): add workout_not_found_at, exclude it from missing-workout queries
A confirmed-404 workout must stop being retried forever, but
workout_raw_json should never be fabricated -- it stays null exactly
as it does for "not yet fetched." workout_not_found_at is the
separate marker ActivitiesMissingWorkout/CountActivitiesMissingWorkout
now check for, mirroring the existing pattern of the other _fetched_at
columns. UpsertActivity's ON CONFLICT clause already never touches
these columns, so the marker persists across every later re-sync.
EOF
)"
```
---
### Task 4: `fillPendingWorkouts` stops retrying a confirmed 404
**Files:**
- Modify: `backend/internal/sync/service.go` (`fillPendingWorkouts`)
- Modify: `backend/internal/sync/service_test.go` (new test)
**Interfaces:**
- Consumes: `garmin.ErrNotFound` (Task 2), `db.SetActivityWorkoutNotFound` (Task 3).
- Produces: nothing new -- this is the final integration point for this fix.
- [ ] **Step 1: Write the failing test**
Add to `backend/internal/sync/service_test.go`, right after
`TestFillPendingDetails_OneWorkoutFetchFailureDoesNotAbortTheWorkoutsPass`:
```go
func TestFillPendingDetails_NotFoundWorkoutStopsBeingRetried(t *testing.T) {
db := openTestDB(t)
ctx := context.Background()
userID := provisionTestUser(t, db)
const missingWorkoutID = 300
missingPtr := int64(missingWorkoutID)
m := &mock.Client{
Activities: []garmin.Activity{
{ActivityID: 1, ActivityType: garmin.ActivityType{TypeKey: "running"}, WorkoutID: &missingPtr,
StartTimeGMT: "2026-07-01 06:00:00", Distance: 5000, Duration: 1500},
},
Splits: map[int64]garmin.ActivitySplits{
1: {ActivityID: 1, Laps: []garmin.Lap{{LapIndex: 1, IntensityType: "ACTIVE"}}},
},
Details: map[int64]garmin.ActivityDetails{1: {ActivityID: 1}},
Workouts: map[int64]garmin.Workout{},
WorkoutErrByID: map[int64]error{missingWorkoutID: fmt.Errorf("API Error 404: %w", garmin.ErrNotFound)},
}
svc := NewService(m, db, userID, Config{InterCallDelay: time.Millisecond},
fixedNow(time.Date(2026, 7, 11, 0, 0, 0, 0, time.UTC)))
if _, err := svc.backfillCore(ctx); err != nil {
t.Fatalf("backfillCore: %v", err)
}
if err := svc.FillPendingDetails(ctx, 10); err != nil {
t.Fatalf("FillPendingDetails should not return an error for a confirmed-404 workout: %v", err)
}
remaining, err := db.CountActivitiesMissingWorkout(ctx, userID)
if err != nil {
t.Fatalf("CountActivitiesMissingWorkout: %v", err)
}
if remaining != 0 {
t.Fatalf("CountActivitiesMissingWorkout = %d, want 0 (confirmed-404 activity must not be retried)", remaining)
}
activities, err := db.ListActivities(ctx, userID, store.ActivityFilter{})
if err != nil {
t.Fatalf("ListActivities: %v", err)
}
if len(activities) != 1 {
t.Fatalf("ListActivities returned %d activities, want 1", len(activities))
}
got, _, err := db.GetActivity(ctx, userID, activities[0].ID)
if err != nil {
t.Fatalf("GetActivity: %v", err)
}
if got.WorkoutNotFoundAt == nil {
t.Error("WorkoutNotFoundAt is nil, want it set")
}
if got.WorkoutRawJSON != nil {
t.Error("WorkoutRawJSON should stay nil -- not-found is recorded separately, not faked")
}
// A second FillPendingDetails call must not attempt this workout again
// (it's no longer in ActivitiesMissingWorkout's result set at all).
if err := svc.FillPendingDetails(ctx, 10); err != nil {
t.Fatalf("second FillPendingDetails: %v", err)
}
}
```
- [ ] **Step 2: Run it to verify it fails**
Run: `cd backend && go test ./internal/sync/... -run TestFillPendingDetails_NotFoundWorkoutStopsBeingRetried -v`
Expected: FAIL -- `CountActivitiesMissingWorkout` still returns 1 (today's code retries forever
regardless of the error's nature).
- [ ] **Step 3: Update `fillPendingWorkouts`**
In `backend/internal/sync/service.go`, replace:
```go
for i, a := range pending {
if i > 0 {
select {
case <-ctx.Done():
return ctx.Err()
case <-time.After(s.cfg.InterCallDelay):
}
}
if err := s.fillActivityWorkout(ctx, a, profile); err != nil {
log.Printf("sync: fill workout for activity %d failed, will retry next sync: %v", a.GarminActivityID, err)
}
s.setProgress(PhaseWorkouts, i+1, len(pending))
}
return nil
}
```
with:
```go
for i, a := range pending {
if i > 0 {
select {
case <-ctx.Done():
return ctx.Err()
case <-time.After(s.cfg.InterCallDelay):
}
}
if err := s.fillActivityWorkout(ctx, a, profile); err != nil {
if errors.Is(err, garmin.ErrNotFound) {
// A definitive 404 (the workout was deleted on Garmin's side
// after being linked to this activity) will never succeed on
// retry -- mark it so ActivitiesMissingWorkout stops
// surfacing it, instead of retrying forever.
log.Printf("sync: workout for activity %d not found on Garmin, marking as such (will not retry): %v", a.GarminActivityID, err)
if serr := s.db.SetActivityWorkoutNotFound(ctx, s.userID, a.ID); serr != nil {
return fmt.Errorf("mark activity %d workout not found: %w", a.GarminActivityID, serr)
}
} else {
log.Printf("sync: fill workout for activity %d failed, will retry next sync: %v", a.GarminActivityID, err)
}
}
s.setProgress(PhaseWorkouts, i+1, len(pending))
}
return nil
}
```
Add `"errors"` to `service.go`'s import block.
- [ ] **Step 4: Run the test to verify it passes**
Run: `cd backend && go test ./internal/sync/... -run TestFillPendingDetails_NotFoundWorkoutStopsBeingRetried -v`
Expected: PASS.
- [ ] **Step 5: Run the full `internal/sync` test suite**
Run: `cd backend && go test ./internal/sync/... -v 2>&1 | tail -60`
Expected: every test passes, including
`TestFillPendingDetails_OneWorkoutFetchFailureDoesNotAbortTheWorkoutsPass` unchanged (its failure
is a plain `fmt.Errorf("garmin says no")`, not `ErrNotFound`-wrapped, so it still hits the
retry-next-sync branch exactly as before).
- [ ] **Step 6: Run the full backend suite**
Run: `cd backend && go build ./... && go vet ./... && gofmt -l . && go test ./...`
Expected: all pass, `gofmt -l .` prints nothing.
- [ ] **Step 7: Commit**
```bash
git add backend/internal/sync/service.go backend/internal/sync/service_test.go
git commit -m "$(cat <<'EOF'
fix(sync): stop retrying a workout Garmin confirms is gone
fillPendingWorkouts previously treated every get_workout_by_id
failure identically -- log it, leave workout_raw_json null, retry
next sync -- which is correct for a transient failure but means a
definitive 404 (the workout deleted on Garmin's side after being
linked to an activity) got silently retried forever, with the only
symptom being an unexplained, permanent "1 more workout pending"
nudge. Now checks errors.Is(err, garmin.ErrNotFound) and, only for
that case, calls SetActivityWorkoutNotFound instead of retrying.
EOF
)"
```
---
## Final verification
- [ ] Run the full backend suite one more time: `cd backend && go build ./... && go vet ./... && gofmt -l . && go test ./...`
- [ ] Run the Python wrapper tests one more time: `cd backend/internal/garmin/pyscript && python3 -m pytest tests/ -v`
- [ ] Confirm `docs/DATABASE.md` reflects the new `workout_not_found_at` column.
- [ ] Use superpowers:finishing-a-development-branch to wrap up (tests green -> present the
merge/PR/keep-as-is menu).