kvitt/PLAN-M5.md

PLAN-M5: Android data layer

1. Goal

Implement :data on top of the Room 3 entities and KvittDatabase v1 that M2b created (D-012): DAOs, the Ktor API client and DTOs, the encrypted token store, the sync engine and its WorkManager workers, every real repository behind the :core:model interfaces, and the APK updater. The phone then works fully offline and syncs per §14.4, proven by tests with Ktor MockEngine and the shared JSON examples.

2. Read first

1. SPEC §14.2 Room entities (14.2.1 Mirrored tables, 14.2.2 Local-only tables, 14.2.3 Migrations, 14.2.4 UI contract).
2. SPEC §14.4 Sync protocol v1, phone side: 14.4.1, 14.4.2 (phone steps), 14.4.3 (request shape), 14.4.5 Phone push procedure, 14.4.6, 14.4.8 Epoch recovery and re-pairing, 14.4.9 Limits and timing.
3. SPEC §14.3 OpenAPI outline (14.3.1 headers, 14.3.2 error codes, 14.3.3 wire objects, 14.3.4 endpoints the app calls, 14.3.5).
4. SPEC §8.2 Device tokens (phone storage), §8.5 Transport, §8.7 Privacy and logging.
5. SPEC §4 FR-2 AC-2.4, AC-2.7 to AC-2.9; FR-3 AC-3.3; FR-4 AC-4.2, AC-4.3, AC-4.6; FR-6 to FR-9 (online-only writes); FR-8 AC-8.6 (defaults), AC-8.10; FR-10 AC-10.4; FR-11 AC-11.3 to AC-11.6; FR-12 AC-12.4, AC-12.5; FR-14 AC-14.1; FR-15 Offline and sync; FR-16 In-app update.
6. SPEC §9.1 to §9.4, §9.6, §9.9 Online-only actions, §9.10.
7. SPEC §6.2 (Local DB, DI, HTTP, Background, Images, Secrets, Tests rows; module table).
8. SPEC §11.2 (row M5), §11.3, §14.7, §14.8.
9. Files: android/data/** as M2b left it (build.gradle.kts, db/Entities.kt, db/KvittDatabase.kt, schemas/se.hagstedt.kvitt.data.db.KvittDatabase/1.json), android/README.md, contracts/examples/**, android/core/model/**, android/domain/**, android/core/fakes/**, android/build-logic/**, android/gradle/libs.versions.toml, CLAUDE.md (BUILD AND VERIFY, ARCHITECTURE RULES, ANTI-PATTERNS, THE PHONE).

3. Already established

• Room 3 (androidx.room3 3.0.3, KSP only, SQLiteDriver with sqlite-bundled; migrations take an SQLiteConnection) (D-012). M2b already created every entity of §14.2.1 and §14.2.2 and KvittDatabase (package se.hagstedt.kvitt.data.db, file kvitt.db, version 1, exportSchema = true); the exported android/data/schemas/se.hagstedt.kvitt.data.db.KvittDatabase/1.json is a contract file (§14.8). M5 adds DAOs to the existing database and does not change the entities or the exported schema; a change it needs is a contract request to the orchestrator (spec bump, decision, next Room version 2 with a migration and migration test). Established for those entities: no foreign keys; names identical to the server's; camelCase properties with @ColumnInfo(name = "snake_case"); server-only columns not mirrored; timestamps String, dates String, money Long, bp Int, booleans Boolean; local_updated_at on every write (§14.2).
• Entity classes, tables, columns, keys and indices exactly as §14.2.1 and §14.2.2; per-phone preferences in DataStore prefs.preferences_pb (§14.2.2).
• Local write semantics: pending = true, new UUIDv7 pending_mutation_id, updated_at = now in the fixed form (and created_at on create), local delete sets deleted_at = updated_at = now; pending count = pending expenses + pending settlements (§14.2.1).
• Pull per page in one Room transaction: epoch check, apply arrays in the fixed order, skip rows with local server_version ≥ incoming and pending expenses/settlements, upsert and replace children, audit insert-or-ignore, cursor and epoch update; repeat while has_more; then last_success_at (§14.4.2).
• Push procedure steps 1 to 4 of §14.4.5, including the re-edit-during-request rule, equal-content rejected treated as accepted, clock_skew handling, 401 handling (device_revoked → AC-3.3 wipe; unauthorized → SessionState.Unrecognised) (§14.4.5, §14.4.8).
• Sync triggers: app start, every foreground, 2 s after the last local write (debounced), every 15 minutes in the background (network constraint), every FCM data message (expedited); one cycle at a time (Mutex; unique work kvitt-sync, KEEP periodic, APPEND_OR_REPLACE one-off); backoff exponential from 30 s (AC-15.3, §14.4.1, §14.4.9).
• Headers on every call: X-Kvitt-Protocol: 1, X-Kvitt-App-Version, Accept-Language, Authorization: Bearer on authenticated calls; 426 → stop syncing and surface update (§14.3.1).
• Token: Android Keystore AES-256-GCM key alias kvitt_token_key, setUserAuthenticationRequired(false), non-exportable; ciphertext and IV in DataStore auth.preferences_pb; base URL, user id, device id in plain text beside it; never logged or put in a URL (§8.2).
• Online-only actions return OnlineResult.Offline without a validated network or within 30 s of a network error; a REST network failure changes nothing locally (§9.9).
• Balances, previews, proposals and analytics are computed in :data with :domain and include pending changes; features never call :domain (§6.2, AC-10.4, AC-14.1).
• Readings fixed in v0.4 (§14.2.4): FieldError.error is a §14.5.3 token, required, or validation_failed for a §9.6 rule without a domain token; analytics() resolves a missing CUSTOM date as today before calling resolveRange (AnalyticsState has no error field; IncompleteCustomRangeException, D-011, is never surfaced); DrillDownState.title is the unlocalised parts joined by ", " (category custom name or lowercase default key, account name, bucket key); a SettlementRow in an account's ledger carries the allocation to that account, elsewhere the settlement total, with accountCount of the whole settlement (AC-11.7).
• Editor defaults from DataStore: last used account if active else oldest active; last used category in that account if active else other (AC-8.6).
• APK updater: release builds call GET /apk/latest on cold start and at most every 6 hours while resumed; download to cache, verify size and SHA-256, install through PackageInstaller; failure deletes the file; debug builds never check (FR-16).
• Pictures through Coil with an auth header, cached by user id and picture_version (AC-4.6, §6.2).
• Tests use Ktor MockEngine and typed fakes; no mocking libraries (§6.2, CLAUDE.md).

4. Owned paths

From SPEC §14.7, verbatim: android/data/** (owner M5; after landing: "later data plans"). Also from §14.7 (row android/settings.gradle.kts, android/build.gradle.kts, android/gradle.properties, android/gradle/**, android/build-logic/**): "later plans may add catalog entries and module includes (rebase resolves)".

Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.

5. Deliverables

• android/data/build.gradle.kts (exists, with Room 3 and KSP): add dependencies :core:model, :domain, Ktor, kotlinx.serialization, WorkManager, DataStore, Hilt, Coil.
• android/data/src/main/kotlin/se/hagstedt/kvitt/data/db/**: DAOs, registered on the existing KvittDatabase (entities as M2b wrote them).
• android/data/schemas/**: unchanged; the build must re-export an identical 1.json (adding DAOs does not change it).
• .../data/api/**: Ktor client with the §14.3.1 headers, DTOs for every wire object and endpoint body, error mapping to §14.3.2 codes.
• .../data/auth/**: Keystore token store, session state.
• .../data/sync/**: sync engine (push, pull, epoch recovery, rejection records), debounce, WorkManager workers.
• .../data/repo/**: real implementations of every repository interface of §14.2.4.
• .../data/update/**: APK updater.
• .../data/connectivity/**: ConnectivityRepository per §9.9.
• .../data/di/**: Hilt modules that :app (M8) can install.
• android/data/src/test/**: DTO round-trip tests over every file in contracts/examples/; sync engine tests with MockEngine for each §14.4 rule including AC-15.6 (14 days offline, 200 changes, scripted clock); repository tests (balances with pending rows, editor defaults, online-only Offline results).
• android/data/src/androidTest/** (if Room needs a device for the schema test; only on the phone the start prompt names).

6. Steps

1. Worktree. From the main checkout /Users/jhag/projects/kvitt: git worktree add .claude/worktrees/agent-m5 -b agent-m5 main, then in .claude/worktrees/agent-m5: git reset --hard main. Copy android/local.properties from the main checkout (add sdk.dir=/opt/homebrew/share/android-commandlinetools if missing; never overwrite or commit). Run tools/install-git-hooks.sh.
2. Read §2 in order. Confirm M2b has landed (android/core/model/ on main); if not, stop and report.
3. Run python3 tools/dependency-report/latest.py; record the lines. Confirm current Room, KSP, Ktor, WorkManager, DataStore and Android Keystore APIs from official documentation (developer.android.com, ktor.io); any new catalog entry at its latest stable version; record versions.
4. Check M2b's entities and 1.json against §14.2.1 and §14.2.2 column by column (report any mismatch as a contract request, do not fix it silently); write the DAOs; confirm 1.json is unchanged after the build.
5. DTOs and the round-trip test over every contracts/examples/** file (decode, re-encode, compare JSON values) before writing the client.
6. Ktor client and error mapping; token store.
7. Sync engine test-first with MockEngine: each pull step, each push result case, epoch recovery, Unrecognised and revoked paths, clock skew, no-progress stop, the AC-15.6 scenario.
8. Repositories, one by one, with tests; workers and triggers; APK updater (verification logic unit-tested; PackageInstaller call isolated behind an interface).
9. Run the gate (§7). Commit on agent-m5, git rebase main, rerun the gate. Never merge, push or remove the worktree.

7. Gate

From SPEC §11.2, verbatim: "Android gate; DTO round-trip tests over every file in contracts/examples/; sync engine tests with Ktor MockEngine covering §14.4 including the 14-day offline case (AC-15.6)". Command, from android/: PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH ../tools/gradle-serial.sh check. Green means: BUILD SUCCESSFUL in this session; fresh XML shows the round-trip test covering every example file (count equals the number of files under contracts/examples/) and the sync tests including AC-15.6, 0 failures.

8. HUMAN steps

From SPEC §11.2, verbatim: "none".

9. Out of scope

• Any UI, ViewModel or string (M7a to M7f; M6 for :core:design).
• :app wiring, navigation, Hilt component installation, FCM service and token registration, notification building, deep links (M8).
• Changing :core:model types or interfaces (contract change via the orchestrator).
• Server code; infra/.

10. Report

• Branch agent-m5, head commit hash after rebasing on main.
• Gate output: BUILD line, actionable tasks line, test counts from fresh XML (round-trip count vs. example file count, sync tests, repository tests).
• Versions added or changed, with sources; dependency-report lines.
• Mapping of §14.4.2 and §14.4.5 rules to test names.
• Numbering used or TODO(spec) occurrences.
• Contract requests (any missing field in §14.2.4, any entity or schema change), open questions, spec gaps (with section numbers).

11. Numbering

Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use TODO(spec) if none was given.