[xameYeoh]

Summary

Adds the local persistence layer for sessions in shared (KMP, SQLDelight): schema, domain models, repository interfaces, SQLDelight-backed implementations, Koin wiring, and host tests. Also records the storage decisions in /docs.

Schema (shared/src/commonMain/sqldelight/.../db/)

• sessions — keyed by uuid; type/status as enums, tags as List<String>, times as kotlin.time.Instant (epoch millis), measurement_interval_millis, optional session_token.
• measurement_streams — FK → sessions ON DELETE CASCADE; unique (session_uuid, sensor_name) so findOrCreate is idempotent.
• measurements — PRIMARY KEY (stream_id, time) + INSERT OR IGNORE. Same dedup key as the backend's v3 rule; replaces legacy (session_id, stream_id, time) index. One table, one write path — no separate active-session buffer table.
• pending_uploads — upload outbox holding only keys (stream_id, time), composite FK → measurements ON DELETE CASCADE. measurements stays insert-only.

Foreign keys are enabled per connection on both platforms (Android driver onOpen callback, iOS extendedConfig.foreignKeyConstraints) — otherwise SQLite ignores ON DELETE CASCADE.

Domain + repositories

• Models: Session, MeasurementStream, Measurement (domain/session).
• SessionRepository, MeasurementStreamRepository, MeasurementRepository, UploadOutbox interfaces, with Local* implementations on Dispatchers.IO.
• MeasurementRepository has two write paths:
  • insertAll — data from elsewhere (downloaded/followed/explored/fixed). Stored only, never enqueued.
  • insertRecorded — data recorded on this phone. Stores and enqueues in one transaction, enqueuing only newly stored rows.
• UploadOutbox.pending(sessionUuid, limit) returns oldest-first; acknowledge deletes outbox rows by natural key (correct when BLE sync backfills older timestamps after newer ones were sent).
• Registered in DatabaseModule (Koin).

Docs

• DOMAIN_KNOWLEDGE.md — averaging is display-only; stored measurements are never averaged/down-sampled/deleted. Dedup key rule updated to (stream_id, time).
• API_V3.md — outbox rules: only locally recorded data is enqueued; 200 ≠ stored (split on finished_at before sending); sync clock before first batch; track per row, never a time cursor; blind retry is safe.
• KMP_ARCHITECTURE.md, ble_mobile_app_guide.md — aligned with the above.

Open decision (noted in API_V3.md): how frames past the server-side finished_at leave the outbox — bound pending by finished_at, or add a state column to pending_uploads.

Tests

androidHostTest (JVM SQLite driver added to that source set):

• SessionRepositoryTest — full-field round-trip, null location, observeAll re-emits on insert, finish sets status + end time together, updateStatus leaves end time alone.
• MeasurementRepositoryTest — findOrCreate idempotent, dedup on (stream, time) incl. partial-overlap counts, same timestamp across streams, location round-trip, lastTime, session delete cascades to streams + measurements.
• UploadOutboxTest — insertRecorded stores + enqueues, insertAll never enqueues, acknowledged duplicate not re-enqueued, pending oldest-first/limited/scoped per session, acknowledge keeps the measurement, failing batch is atomic, session delete clears pending uploads.

Out of scope

Uploader itself, read-side averaging, UI wiring.

🤖 Generated with Claude Code