Merge branch 'main' into feat/mood-level-b

docs/api/openapi.yaml

@@ -3405,12 +3405,16 @@ paths:
       tags:
         - Measurements
       summary: Typed workout batch ingest (v1.4.25 W16b)
-      description: Server-side ingest endpoint for HKWorkout records (iOS) and Withings activity rows (server-to-server). Up
+      description: 'Server-side ingest endpoint for HKWorkout records (iOS) and Withings activity rows (server-to-server). Up
         to 100 workouts per call; nested route geometry (GeoJSON LineString) is capped at 20 000 points and stored in a
         1:1 `WorkoutRoute` row keyed by `workoutId`. Idempotent via the `Idempotency-Key` header (replay window 24h).
-        Per-entry status (`inserted | duplicate | skipped`) lets the iOS sync cursor checkpoint accurately. The request
-        body ceiling is 5 MB enforced at the HTTP layer — clients above the ceiling receive a 413 with
-        `workout.batch.payload_too_large`.
+        Per-entry status (`inserted | duplicate | enriched | skipped`) lets the iOS sync cursor checkpoint accurately.
+        An entry matching a stored workout is first-write-wins for the workout row; when it carries a `samples` array
+        and the stored workout has no heart-rate series, the series is attached and the entry reports `enriched`
+        (repeatable: a workout that already has a series is a no-op). An entry whose `samples` array fails validation is
+        refused on its own with `reason: "invalid_samples"` — the rest of the batch still lands. The request body
+        ceiling is 5 MB enforced at the HTTP layer — clients above the ceiling receive a 413 with
+        `workout.batch.payload_too_large`.'
       requestBody:
         required: true
         content:
@@ -21923,14 +21927,19 @@ components:
           type: integer
           minimum: 0
           maximum: 9007199254740991
+          description: Entries in the request. Equals `inserted + duplicates + skipped.length`.
         inserted:
           type: integer
           minimum: 0
           maximum: 9007199254740991
+          description: Workout rows this request wrote.
         duplicates:
           type: integer
           minimum: 0
           maximum: 9007199254740991
+          description: Entries that wrote no workout row because the workout was already stored. The top-level counters count
+            workout rows, so an entry reported as `enriched` counts here as well even though its heart-rate series was
+            attached.
         skipped:
           type: array
           items:
@@ -21969,8 +21978,15 @@ components:
           enum:
             - inserted
             - duplicate
+            - enriched
             - skipped
+          description: "`inserted`: a new workout row. `duplicate`: the workout was already stored and nothing was written.
+            `enriched`: the workout was already stored and the heart-rate series this entry carried was attached to it;
+            the workout row itself was not written, and the entry also counts towards the top-level `duplicates`.
+            `skipped`: the server refused the entry, see `reason`."
         reason:
+          description: "Why a `skipped` entry was refused: `unstable_external_id` for an id that does not survive a client
+            restart, `invalid_samples` for a heart-rate series that failed validation."
           type: string
       required:
         - index