loto/plans/reports/fullstack-developer-260831-2314-android-backup-settings.md

Fix report: Android backup rules (L9) + settings-loaded signal (M4 residual)

Phase 2 of plans/260831-2314-review-followups/plan.md. Scope: two decisions delegated by the user — exclude game-state DataStore from backup/transfer, keep settings backed up; close the M4 residual race (master restore landing before settings resolves) with an explicit settings-loaded signal.

Item A — backup rules

Verified on-disk DataStore names from LotoApplication.kt's preferencesDataStore(name = ...) delegates: loto_settings and loto_game_state. androidx.datastore.preferences.preferencesDataStore's default file location is files/datastore/<name>.preferences_pb, so the excluded path is datastore/loto_game_state.preferences_pb.

• New android/app/src/main/res/xml/data_extraction_rules.xml — API 31+, excludes that path from both <cloud-backup> and <device-transfer>.
• New android/app/src/main/res/xml/backup_rules.xml — full-backup-content counterpart for API 24-30 (minSdk 24, so this path is live).
• AndroidManifest.xml: added android:dataExtractionRules and android:fullBackupContent to <application>; android:allowBackup="true" left unchanged. Settings DataStore is not mentioned anywhere in either XML, so it stays backed up/transferred by default.

Item B — M4 residual: settings-loaded signal

Root cause (confirmed by reading PlayerAutoCross.applyMasterCalls): the cursor advances to called.size on every non-BOTH pass even when nothing changes. If masterStore.restore() lands with the full history before the settings DataStore read resolves, the prior combine() fix still evaluates that first master emission with settings.value.mode at its PLAYER default, consumes the cursor to called.size, and the later real-mode arrival finds cursor >= called.size — replay lost, permanently, since masterStore.state doesn't re-emit until the next draw.

Fix — a loaded signal threaded end to end:

• settings/SettingsRepository.kt: new val loaded: Flow<Boolean> = settingsFlow.map { true }.onStart { emit(false) } — cold, derived purely from settingsFlow, mirrors the existing settingsFlow/settingsState pairing rather than adding a scope to the repository.
• LotoApplication.kt: new val settingsLoaded: StateFlow<Boolean> = settingsRepository.loaded.stateIn(appScope, SharingStarted.Eagerly, false), next to settingsState.
• state/PlayerBoardViewModel.kt: new constructor param settingsLoaded: StateFlow<Boolean> = MutableStateFlow(true) (defaults to "already loaded" so every existing call site, including all prior tests, is unaffected). init's collector changed from combine(masterStore.state, settings) { master, _ -> master }.collect { onMasterState(it) } to combine(masterStore.state, settings, settingsLoaded) { master, _, loaded -> master to loaded }.collect { (master, loaded) -> if (loaded) onMasterState(master) }. While !loaded, onMasterState is skipped entirely — lastHandledIndex stays untouched — so once settingsLoaded flips true, combine's cached master snapshot is re-delivered and replayed under the real mode.
• state/LotoViewModelFactory.kt: passes settingsLoaded = app.settingsLoaded to the production PlayerBoardViewModel. This file isn't in the plan's Phase 2 file-ownership list but is load-bearing — without it the fix would only exist in test wiring, not in the shipped app. The direct task instructions ("Files you may modify: anything under android/") permit it.
• state/MasterPanelViewModel.kt / state/MasterStore.kt: unchanged. Neither consumes master emissions through the mode-gated cursor the task scoped this fix to; MasterPanelViewModel reads settings.value synchronously per-draw with no persistent cursor to corrupt.
• H1/loading behavior (restore vs. in-flight user action, from the prior fix pass) is untouched — restore()/publish(loading = ...) logic wasn't touched, and the H1 regression tests in PlayerBoardViewModelTest still pass unmodified.

Tests

• settings/SettingsRepositoryTest.kt: new loaded stays false until the first DataStore read resolves — SlowDataStore + CompletableDeferred gate, collects loaded into a list via backgroundScope, asserts [false] before the gate opens and [false, true] after.
• state/PlayerBoardViewModelTest.kt: new master restore landing with full history before settings resolves still replays under the real mode (M4 residual) — builds a real SettingsRepository over a gated SlowDataStore (mode persisted as BOTH ahead of time on the ungated backing store), constructs the ViewModel with settingsFlow/loaded stateIn'd the same way LotoApplication does, resolves masterStore with the full 90-number history before completing the settings gate, asserts nothing crossed yet, then completes the gate and asserts the full board replays (rowComplete all true).
• Verified fail-without-fix: temporarily reverted the init collector to the pre-fix combine(...) { master, _, _ -> master }.collect { onMasterState(it) } (ignoring loaded) and reran :app:testDebugUnitTest --tests "...PlayerBoardViewModelTest" — exactly the new regression test failed (18 others passed), confirming it actually exercises the closed gap. Reverted back to the fix immediately after.
• Fixed a pre-existing opt-in warning while touching SettingsRepositoryTest.kt (@OptIn(ExperimentalCoroutinesApi::class) on the class, matching the pattern already used in PlayerBoardViewModelTest.kt) since the new test needed runCurrent.

Verification

JAVA_HOME="C:/Program Files/Eclipse Adoptium/jdk-21.0.10.7-hotspot" ./gradlew :app:testDebugUnitTest :app:lintDebug

BUILD SUCCESSFUL, all unit tests pass (including the two new ones), lint clean. Not committed, per instructions.

Files changed

• android/app/src/main/AndroidManifest.xml
• android/app/src/main/res/xml/data_extraction_rules.xml (new)
• android/app/src/main/res/xml/backup_rules.xml (new)
• android/app/src/main/java/com/miti99/loto/settings/SettingsRepository.kt
• android/app/src/main/java/com/miti99/loto/LotoApplication.kt
• android/app/src/main/java/com/miti99/loto/state/PlayerBoardViewModel.kt
• android/app/src/main/java/com/miti99/loto/state/LotoViewModelFactory.kt
• android/app/src/test/java/com/miti99/loto/settings/SettingsRepositoryTest.kt
• android/app/src/test/java/com/miti99/loto/state/PlayerBoardViewModelTest.kt

Note: git status also shows other android files modified/new (build.gradle.kts, MainActivity.kt, MasterStore.kt, GameStateRepository.kt, MasterPanelViewModel.kt, ColorParsing.kt, UI files, MasterStoreTest.kt, ThrowingDataStore.kt, etc.) — these are pre-existing uncommitted changes from the earlier fullstack-developer-260831-2226 fix pass, not touched by this task.

Unresolved questions

None.

Status: DONE Summary: Added API-31+ and pre-31 backup-exclusion rules for the game-state DataStore only (settings stay backed up), and closed the M4 residual race with a SettingsRepository.loaded/LotoApplication.settingsLoaded signal that gates PlayerBoardViewModel's master-emission consumption until settings have really resolved; new regression test verified to fail without the fix. :app:testDebugUnitTest and :app:lintDebug both green. Concerns/Blockers: none.