[P2/high] feat(web): offline-first set logging sync queue (vires-ops#48)

[ne-groomer]

Priority: P2 · Complexity: high

Closes nousergon/vires-ops#48

Design decision (settled by the Opus groomer — not re-litigated)

Append-wins with client-generated set UUIDs. Each logged set is an immutable append keyed by a client-minted crypto.randomUUID(). While offline (or when an online POST fails) the write is parked in IndexedDB; on reconnect it's replayed and deduped server-side on the client UUID, so a replay is idempotent. For an append-only set log this is near-conflict-free by construction — the correct low-risk choice over merge / server-authoritative.

Storage-cap UX: the IndexedDB queue is capped at 500 pending writes; on overflow it drops the oldest and logs a console.warn (documented in web/README.md). Safer than an unbounded queue that silently hits the IndexedDB quota — the newest sets the user just performed stay queued.

Retry/backoff: failed replays are retained with bounded exponential backoff (1s → 5min cap) and dropped after 12 attempts so one poison write can't wedge the queue.

What changed

Frontend (web/)

• src/lib/setQueue.ts — durable IndexedDB queue (vires-offline DB / pending-sets store, keyed by client UUID): add/list/remove/clear/count, size cap with drop-oldest + warning, exponential-backoff helpers. Backend-agnostic behind a QueueBackend interface so it unit-tests in jsdom without a real IndexedDB.
• src/lib/setSync.ts — write path (logSetOfflineFirst: mint UUID; POST immediately when online, else enqueue + register a Background-Sync tag), drainQueue replay engine (remove on 2xx ack, backoff on failure, drop after max attempts), and installOnlineReplay fallback for browsers without Background Sync.
• public/sync-sw.js — service worker sync (and message) handler that drains the queue; imported into the workbox-generated SW alongside push-sw.js via vite.config.ts importScripts (push notifications untouched; verified both scripts land in the built dist/sw.js).
• src/pages/WorkoutPage.tsx — addSet routes the set-create through logSetOfflineFirst.
• src/App.tsx — installs the online-event replay fallback on mount.
• src/lib/setQueue.test.ts, src/lib/setSync.test.ts — Vitest suites for enqueue/cap/backoff and online/offline write path + replay/dedup/backoff/drop. Updated one existing WorkoutPage assertion for the new client_uuid in the POST body.

Backend (api/)

• api/db/models.py — SetEntry.client_uuid nullable column + UniqueConstraint(session_exercise_id, client_uuid).
• alembic/versions/d9e0f1a2b3c4_set_entry_client_uuid.py — migration adding the column + unique index (batch_alter for SQLite; up/down verified).
• api/routers/workouts.py — log_set dedupes on client_uuid (returns the existing row on replay; race-safe via IntegrityError rollback → return winner). _set_out echoes it.
• api/schemas/workout.py — SetIn/SetOut carry client_uuid.
• tests/test_workouts.py — replay-dedup (one row, same id), distinct-UUID append, per-session_exercise scoping, null-UUID unchanged, echo.

Schema / migration

New nullable column set_entries.client_uuid + unique index uq_set_entries_se_client_uuid on (session_exercise_id, client_uuid). Nullable so online writes and every pre-existing row need no UUID; SQLite/Postgres treat multiple NULLs as distinct, so unlabeled rows never collide. Migration d9e0f1a2b3c4 (down_revision b3c4d5e6f7a8); alembic upgrade head and downgrade -1 both verified against SQLite.

Validation (all run, all green)

Backend (repo root, python3.12 venv, pip install -e ".[dev]" + ruff/pytest):

• ruff check . → pass (All checks passed)
• pytest → pass (full suite, ~400 tests; pytest tests/test_workouts.py 27/27 incl. 5 new dedup tests)
• alembic upgrade head / alembic downgrade -1 → pass

Frontend (web/, npm ci):

• npm run lint (oxlint) → pass (0 errors; 1 pre-existing warning in an untouched file)
• npm run build (tsc -b && vite build) → pass (SW generated; importScripts("/push-sw.js","/sync-sw.js") confirmed in dist/sw.js)
• npm run test (vitest) → pass (160/160; coverage above all gate thresholds: stmts 67.4% / branches 65.6% / funcs 62.4% / lines 69.6%)

Note: the groom box ships Node 18; Vite 8 / Vitest 4 require Node 20+, so build/test were run under a local Node 22.12 (the missing linux-x64-gnu native bindings for oxlint/rolldown — normally pulled by npm as optional deps — were fetched to run the toolchain). No source or lockfile change was needed for this.

---

Groom-Run: cbb048a29c4a4505999e48322ae6571f