[xameYeoh]

Summary

Adds the client side of uploading mobile sessions to /api/v3: creating the session, sending measurements in batches as binary frames, and finishing it. The code is three layered classes in
data/network/upload/. Each one can be called again after a failure and picks up where it stopped.

The class that decides when uploads run (the outbox-observing loop, plus WorkManager / beginBackgroundTask as a backstop) is not built here. Its design is agreed and written down in
docs/API_V3.md → When the uploader runs.

What's in it

MobileMeasurementPayload: binary frame encoder

• Writes the v3 mobile measurement format: header 0xAB 0xBA + uint16 frame count, then one frame per measurement (int32 epoch seconds, uint8 sensor_type_id, float32 value, float64 lat,
  float64 lng), then a trailing XOR checksum.
• Rejects an empty batch, more than MaxFrames = 3000 frames, and any sensor_type_id outside 1..255.

MobileMeasurementUploader: sends one session's outbox

• Takes the session's pending rows in batches of up to 3000 and POSTs each batch to /mobile_sessions/{uuid}/measurements.
• A row is removed from the outbox (acknowledged) only after the server accepts its batch. If a request fails, the exception propagates and the unsent rows stay queued.
• A row it can't send (its stream has no sensor_type_id, or the row has no location) is skipped and logged as an error. It stays in the outbox and is never dropped silently.

MobileSessionUpload: brings one session up to date

Runs create (once) → upload outbox → /finish (once, after stop). Each step is skipped if it was already done:

• Create runs only while some local stream still has no sensor_type_id. The ids from the response are written back to the local streams.
• 409 recovery: a 409 on create means an earlier create reached the server but its response was lost. In that case the ids are read back with GET /mobile_sessions/{uuid}.
• Finish sends the phone's own end_time as finished_at, then sets the new is_finished_on_server flag.

API / DTO changes

• CreateMobileSessionRequestDto now has a flat body (the session wrapper is gone) and adds device { mac_address, model }, tag_list and a required streams.
• createSession now returns CreateMobileSessionResponseDto (streams[] { sensor_name, sensor_type_id }).
• New finishSession(token, uuid, finishedAt) and the v3MobileSessionFinish endpoint.
• GET session/list DTOs now include streams, keyed by sensor_name. This is what the 409 read-back uses.

Persistence

• sessions.is_finished_on_server column, markFinishedOnServer query, and a matching method on SessionRepository.
• Renamed contribute → is_contributing_to_crowd_map. The JSON name stays contribute via @SerialName.

Boolean naming refactor (mechanical)

Boolean fields across the app now read as questions: granted → isGranted, darkMode → isDarkMode, contribute → isContributingToCrowdMap, and the same in auth, settings, mic and custom-server. No behavior change.

Decisions recorded in docs

• docs/API_V3.md
  • Every stream must be sent in the create call: v3 can't add a stream later, and a frame needs a sensor_type_id.
  • The create body is flat; a 409 is recovered with the GET read-back.
  • The client sends its own finished_at, so upload and /finish can run in either order.
  • No client-side clock checks.
  • Upload scheduling: runs live, driven by the outbox, 60 s batching while recording, exponential backoff, platform backstops. iOS force-quit limit noted.
• docs/DOMAIN_KNOWLEDGE.md
  • Location stamping when a measurement is stored, with the legacy fallback chain (V2MobileMeasurementsInserter).
  • When the legacy app triggered sync.
  • The app uploads mobile measurements only (AB3 SD-sync is the one exception, not built yet).
• CLAUDE.md: when a business rule isn't covered by /docs/, take it from the legacy app's code and record it in /docs/.

⚠️ Notes for reviewers

• Schema change without a migration: a column was renamed and is_finished_on_server was added directly in Session.sq, with no .sqm file. That's fine before release, but any existing local install needs a clean reinstall or app-data wipe.
• Nothing calls MobileSessionUpload yet. That comes with the trigger loop in a follow-up.

Tests

• MobileMeasurementPayloadTest: byte layout, checksum, input limits.
• MobileMeasurementUploaderTest: batching at 3000, acknowledge only on success, skipped unsendable rows, no token → nothing sent.
• MobileSessionUploadTest: create once and write the ids back, 409 read-back, skip create when ids exist, finish only after stop and only once, resume after a partial failure.
• Shared fakes in UploadFakes.kt; existing tests updated for the boolean renames.