General: Dedupe DataStore reads by porting SD Maid SE's DataStoreValue DSL (#26)

Amply keeps one shared Preferences DataStore, and Preferences DataStore
hands the entire snapshot to every collector on any write. None of the 14
preference flows deduplicated, so an unrelated write woke all of them.

That was user-visible: ChargeStatsRecorder stamps lastCaptureWallMillis on
every recorded sample (~20s while charging, always a new timestamp), which
re-emitted captureEnabled unchanged, restarted the flatMapLatest in
statsDashboardStates and replayed its loading marker — collapsing the
dashboard's charging card to its loading size for a frame, every 20s.

Settings are now declared with a createValue() DSL in common/datastore,
which dedupes on the raw stored value before the reader runs. The guard
lives in the primitive, so a facade cannot forget it, and it never depends
on a domain type's equals.

Settings read as a unit — a session and its provenance, the recovery
target, the interruption event, the alarm config, theme and quick-access
state — are now one @serializable record under one key (new dependency:
kotlinx-serialization-json), so a partially-written state cannot exist and
read-modify-write collapses to update {}. Independent scalars stay
separate so a hot-path write doesn't wake unrelated collectors.

Corruption semantics are chosen per record rather than globally. Records
whose decode was already all-or-nothing keep a whole-record fallback, but
ChargingPreferences parses field by field: its four facts degrade
independently, and a wholesale fallback would silently downgrade a user's
90% protective baseline to the 80% default and then persist the downgrade.
For the same reason every field except the charge policy itself is
optional — a missing pid must not take an owed restore down with it.

Also fixes a pre-existing torn read in InterruptionAssessor, which read
recovery provenance, work id and session through separate suspend calls
and could pair fields from either side of a concurrent adopt or clear.

No migration: old keys are abandoned and new ones are suffixed .v2. Test
users only. An update installed mid-session therefore loses that session's
record — wipe app data before installing.

Verified: 706 tests pass on both flavors; lintVital clean on all four
beta/release variants; R8 release builds clean with no serialization
stripping. Both blip regression tests were confirmed against a negative
control (removing the dedupe makes them fail: 6 emissions instead of 2,
providers recreated 4x instead of 1x), as were the per-field corruption,
missing-metadata and alarm-normalization guards.

Author: d4rken

.claude/CLAUDE.md

@@ -47,6 +47,8 @@ Under `app/src/main/java/eu/darken/amply/`:
 - `main/ui` — activity, onboarding, dashboard, settings, setup guide, `tile`, `widget`
 - `diagnostics/core` + `diagnostics/ui` — privileged settings comparison and its guided UI
 - `common` — shared DataStore owner (`AppDataStore`) and cross-feature primitives
+- `common/datastore` — the `createValue()` settings DSL every preference facade is built on (`DataStoreValue`)
+- `common/serialization` — the single `Json` plus `ChargePolicySerializer`, for JSON-backed setting records
 - `common/theming` — brand, Material You, mode, contrast preferences
 - `common/settings` — reusable hierarchical settings rows/sections
 - `common/debug/logging` — opt-in debug sessions and logging backends

.claude/rules/architecture.md

@@ -27,7 +27,10 @@ eu.darken.amply
     └── debug/logging        Logging fan-out + backends (Logcat, File)
 ```
 
-Feature-specific preference facades live with their owning feature but share the one `AppDataStore` instance.
+Feature-specific preference facades live with their owning feature but share the one `AppDataStore` instance. They
+declare their settings with the `createValue()` DSL (`common/datastore`) rather than touching `store.data` — with a
+single shared store, every write reaches every collector, so the deduplication has to live in the primitive. See
+`code-style.md`.
 
 ## Data Flow
 

.claude/rules/code-style.md

@@ -106,7 +106,29 @@ Debug logs stay **local**: the file logger records only after explicit consent,
 
 - Reactive with Kotlin Flow / StateFlow.
 - **Preferences DataStore** via the single `AppDataStore` (`common/AppDataStore.kt`) — `preferencesDataStore(name = "amply")`.
-  This is the raw AndroidX Preferences API (read/write `Preferences.Key`s through `store.data` / `store.edit`); there
-  is no custom `createValue()` typed-setting DSL. Feature preference facades wrap `AppDataStore` but all share the one
-  process-safe instance — do not create a second `DataStore`.
+  Feature preference facades wrap `AppDataStore` but all share the one process-safe instance — do not create a second
+  `DataStore`.
+- **Never read `store.data` directly in a facade.** Declare settings with the `createValue()` DSL in
+  `common/datastore/` (ported from SD Maid SE). Because there is exactly one shared store, Preferences DataStore hands
+  the *entire* snapshot to *every* collector on *any* write — an unrelated key's write would otherwise re-emit every
+  setting in the app, restarting downstream `flatMapLatest` chains and rebuilding whole UI states. `DataStoreValue`
+  dedupes on the **raw stored value, before the reader runs**, so the guard cannot be forgotten per-facade and never
+  depends on a domain type's `equals`. (This is not hypothetical: an undeduplicated `captureEnabled` made the
+  dashboard's charging card flash its loading state on every stats-recorder tick.)
+
+  ```kotlin
+  val captureEnabled = dataStore.createValue("stats.capture_enabled", false)   // scalar
+  val session = dataStore.createValue<ChargeSessionRecord?>("session.v2", null, json, fallbackToDefault = true)
+  ```
+
+  Read with `.value()` / collect `.flow`; write with `.value(x)` or `.update { }` (read-modify-write in one
+  transaction). Settings consumed **as a unit** — a session and its provenance, the alarm config — are one
+  `@Serializable` record under one key, so a partially-written state cannot exist. Independent scalars stay separate,
+  so a hot-path write doesn't wake unrelated collectors.
+- **Persisted records are a stored wire format.** Give every persisted property and enum constant an explicit
+  `@SerialName` and a default, and never reuse a key name for a different type (Preferences keys compare by name).
+  `fallbackToDefault` is chosen **per record**: fine where the decode is already all-or-nothing (an unreadable session
+  is no session) or cosmetic, but a record whose fields degrade *independently* — `ChargingPreferences` — must
+  validate field by field, or one bad field silently resets a user's real protective baseline to the default.
+  `StoredRecordFormatTest` pins the JSON.
 - Debug builds attach extra logging; the file logger requires explicit user consent before recording.

app/build.gradle.kts

@@ -30,6 +30,7 @@ plugins {
     id("projectConfig")
     id("com.android.application")
     id("org.jetbrains.kotlin.plugin.compose")
+    id("org.jetbrains.kotlin.plugin.serialization")
     id("com.google.devtools.ksp")
     id("com.google.dagger.hilt.android")
     id("com.android.compose.screenshot")
@@ -193,6 +194,7 @@ tasks.withType<KotlinCompile>().configureEach {
         jvmTarget.set(JvmTarget.JVM_17)
         freeCompilerArgs.addAll(
             "-opt-in=kotlinx.coroutines.ExperimentalCoroutinesApi",
+            "-opt-in=kotlinx.serialization.ExperimentalSerializationApi",
             "-opt-in=androidx.compose.material3.ExperimentalMaterial3Api",
             "-Xannotation-default-target=param-property",
         )

app/src/main/java/eu/darken/amply/alarm/core/ChargeAlarmStore.kt

@@ -1,21 +1,23 @@
 package eu.darken.amply.alarm.core
 
-import androidx.datastore.preferences.core.Preferences
-import androidx.datastore.preferences.core.booleanPreferencesKey
-import androidx.datastore.preferences.core.edit
-import androidx.datastore.preferences.core.intPreferencesKey
 import eu.darken.amply.common.AppDataStore
+import eu.darken.amply.common.datastore.createValue
+import eu.darken.amply.common.datastore.value
 import kotlinx.coroutines.flow.Flow
-import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.map
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
 import javax.inject.Inject
 import javax.inject.Singleton
 import kotlin.math.roundToInt
 
-/** User-facing charge-alarm configuration, derived from a single DataStore snapshot. */
+/** User-facing charge-alarm configuration, persisted as one record. */
+@Serializable
 data class ChargeAlarmConfig(
-    val enabled: Boolean = false,
-    val targetPercent: Int = DEFAULT_TARGET_PERCENT,
+    @SerialName("enabled") val enabled: Boolean = false,
+    @SerialName("targetPercent") val targetPercent: Int = DEFAULT_TARGET_PERCENT,
 ) {
     companion object {
         const val DEFAULT_TARGET_PERCENT = 80
@@ -27,43 +29,56 @@ data class ChargeAlarmConfig(
 
 /**
  * DataStore facade for the charge alarm, sharing the single [AppDataStore]. Exposes the config as
- * one flow (mapped from a single snapshot, so `enabled` and `targetPercent` never transiently
- * disagree) plus the durable "fired this plug cycle" latch that makes the alarm fire at most once
+ * one record — `enabled` and `targetPercent` live under a single key, so they can never transiently
+ * disagree — plus the durable "fired this plug cycle" latch that makes the alarm fire at most once
  * per charge even across process death.
+ *
+ * The latch is a separate value on purpose: it is written by the watcher on a completely different
+ * cadence than the user's config, and folding it into the record would wake every config collector
+ * each time the alarm fires or resets.
  */
 @Singleton
 class ChargeAlarmStore @Inject constructor(
-    private val dataStore: AppDataStore,
+    dataStore: AppDataStore,
+    json: Json,
 ) {
-    val config: Flow<ChargeAlarmConfig> = dataStore.store.data.map(::toConfig)
+    private val configValue = dataStore.createValue(
+        key = "alarm.config.v2",
+        defaultValue = ChargeAlarmConfig(),
+        json = json,
+        fallbackToDefault = true,
+    )
+
+    private val firedCycleValue = dataStore.createValue("alarm.fired_cycle.v2", false)
+
+    /**
+     * Normalized on the way out — the setter snaps too, but a hand-edited or future-written record
+     * could still carry an off-step target and the UI's stepper assumes a valid tick.
+     *
+     * Deduped *again* after normalizing, because snapping is many-to-one: a stored 83 and a
+     * subsequent explicit 85 are two distinct raw records that both normalize to 85, so the upstream
+     * raw-value dedupe cannot catch the duplicate.
+     */
+    val config: Flow<ChargeAlarmConfig> = configValue.flow.map(::normalize).distinctUntilChanged()
 
-    suspend fun configNow(): ChargeAlarmConfig = config.first()
+    suspend fun configNow(): ChargeAlarmConfig = normalize(configValue.value())
 
     suspend fun setEnabled(enabled: Boolean) {
-        dataStore.store.edit { it[ENABLED] = enabled }
+        configValue.update { it.copy(enabled = enabled) }
     }
 
     suspend fun setTargetPercent(percent: Int) {
-        dataStore.store.edit { it[TARGET_PERCENT] = normalizeTarget(percent) }
+        configValue.update { it.copy(targetPercent = normalizeTarget(percent)) }
     }
 
     /** Whether the alarm has already fired (or been suppressed) for the current plug cycle. */
-    suspend fun firedCycle(): Boolean = dataStore.store.data.first()[FIRED_CYCLE] ?: false
+    suspend fun firedCycle(): Boolean = firedCycleValue.value()
 
     suspend fun setFiredCycle(fired: Boolean) {
-        dataStore.store.edit { it[FIRED_CYCLE] = fired }
+        firedCycleValue.value(fired)
     }
 
-    private fun toConfig(prefs: Preferences) = ChargeAlarmConfig(
-        enabled = prefs[ENABLED] ?: false,
-        targetPercent = normalizeTarget(prefs[TARGET_PERCENT] ?: ChargeAlarmConfig.DEFAULT_TARGET_PERCENT),
-    )
-
-    private companion object {
-        val ENABLED = booleanPreferencesKey("alarm.enabled")
-        val TARGET_PERCENT = intPreferencesKey("alarm.target_percent")
-        val FIRED_CYCLE = booleanPreferencesKey("alarm.fired_cycle")
-    }
+    private fun normalize(raw: ChargeAlarmConfig) = raw.copy(targetPercent = normalizeTarget(raw.targetPercent))
 }
 
 /** Snap to the nearest [ChargeAlarmConfig.TARGET_STEP] and clamp to the allowed range. */

app/src/main/java/eu/darken/amply/charging/core/ChargingPreferences.kt

@@ -1,69 +1,134 @@
 package eu.darken.amply.charging.core
 
-import androidx.datastore.preferences.core.edit
-import androidx.datastore.preferences.core.longPreferencesKey
 import androidx.datastore.preferences.core.stringPreferencesKey
 import eu.darken.amply.common.AppDataStore
+import eu.darken.amply.common.datastore.createValue
+import eu.darken.amply.common.datastore.value
 import kotlinx.coroutines.flow.Flow
-import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.map
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
 import javax.inject.Inject
 import javax.inject.Singleton
 
+/**
+ * The stored form of Amply's policy bookkeeping.
+ *
+ * Policies are held as **raw [ChargePolicy.stableId] strings**, not as decoded `ChargePolicy`s,
+ * because these four facts degrade *independently*: an unreadable `lastRequested` must still leave a
+ * perfectly good `protective` baseline intact. Losing that baseline is not cosmetic — it is the
+ * limit Amply restores the battery to, so a wholesale fallback would quietly downgrade a user's
+ * Adaptive or 90 % choice to the 80 % default, and the next write would persist the downgrade.
+ *
+ * Which is why decoding goes through [decodePolicyState] field by field instead of
+ * `decodeFromString`: a typed whole-record decode fails on the *first* bad field and takes the other
+ * three with it, so `{"lastRequestedAt":"bad", "protective":"fixed:90"}` would lose a valid 90 %.
+ */
+@Serializable
+internal data class PolicyState(
+    @SerialName("lastRequested") val lastRequested: String? = null,
+    @SerialName("lastRequestedAt") val lastRequestedAt: Long = 0L,
+    @SerialName("protective") val protective: String? = null,
+    @SerialName("lastPersistent") val lastPersistent: String? = null,
+)
+
+/**
+ * Reads each field on its own terms. A field that is absent, the wrong JSON type, or an unreadable
+ * policy id yields only *that* field's default; only unparseable JSON loses the whole record.
+ */
+internal fun decodePolicyState(raw: String?, json: Json): PolicyState {
+    if (raw == null) return PolicyState()
+    val obj = runCatching { json.parseToJsonElement(raw) as? JsonObject }.getOrNull() ?: return PolicyState()
+    return PolicyState(
+        lastRequested = obj.stringOrNull("lastRequested"),
+        lastRequestedAt = obj.longOrDefault("lastRequestedAt"),
+        protective = obj.stringOrNull("protective"),
+        lastPersistent = obj.stringOrNull("lastPersistent"),
+    )
+}
+
+private fun JsonObject.primitiveOrNull(name: String): JsonPrimitive? =
+    (this[name] as? JsonPrimitive)?.takeUnless { it is JsonNull }
+
+private fun JsonObject.stringOrNull(name: String): String? = primitiveOrNull(name)?.takeIf { it.isString }?.content
+
+private fun JsonObject.longOrDefault(name: String, default: Long = 0L): Long =
+    primitiveOrNull(name)?.takeUnless { it.isString }?.content?.toLongOrNull() ?: default
+
 @Singleton
 class ChargingPreferences @Inject constructor(
-    private val dataStore: AppDataStore,
+    dataStore: AppDataStore,
+    json: Json,
 ) {
-    val lastRequested: Flow<ChargePolicy?> = dataStore.store.data.map {
-        ChargePolicy.fromStableId(it[LAST_REQUESTED])
-    }
+    private val policyState = dataStore.createValue(
+        key = stringPreferencesKey("policy.v2"),
+        reader = { raw -> decodePolicyState(raw as? String, json) },
+        writer = { state -> json.encodeToString(PolicyState.serializer(), state) },
+    )
+
+    // Each projection dedupes on its own: they all ride one record now, so without this a
+    // lastRequestedAt-only write would re-emit every one of them.
+    val lastRequested: Flow<ChargePolicy?> = policyState.flow
+        .map { ChargePolicy.fromStableId(it.lastRequested) }
+        .distinctUntilChanged()
 
     /** Wall-clock time of the last request; paired atomically with [lastRequested]. 0 = never requested. */
-    val lastRequestedAt: Flow<Long> = dataStore.store.data.map { it[LAST_REQUESTED_AT] ?: 0L }
+    val lastRequestedAt: Flow<Long> = policyState.flow
+        .map { it.lastRequestedAt }
+        .distinctUntilChanged()
 
-    val protectivePolicy: Flow<ChargePolicy> = dataStore.store.data.map {
-        ChargePolicy.fromStableId(it[PROTECTIVE_POLICY])?.takeUnless { policy ->
-            policy == ChargePolicy.Unrestricted
-        } ?: ChargePolicy.FixedLimit(80)
-    }
+    val protectivePolicy: Flow<ChargePolicy> = policyState.flow
+        .map { it.protectivePolicy() }
+        .distinctUntilChanged()
 
     /**
      * The last policy Amply successfully applied as a *persistent* configuration — including
      * [ChargePolicy.Unrestricted], unlike [protectivePolicy]. Temporary session overrides never
      * update this, so it answers "what did the user configure through Amply" without a session's
      * transient Unrestricted write polluting the answer. Null until Amply's first persistent write.
      */
-    val lastPersistentPolicy: Flow<ChargePolicy?> = dataStore.store.data.map {
-        ChargePolicy.fromStableId(it[LAST_PERSISTENT_POLICY])
-    }
+    val lastPersistentPolicy: Flow<ChargePolicy?> = policyState.flow
+        .map { ChargePolicy.fromStableId(it.lastPersistent) }
+        .distinctUntilChanged()
 
     suspend fun recordRequested(
         policy: ChargePolicy,
         persistent: Boolean,
         nowMillis: Long = System.currentTimeMillis(),
     ) {
-        dataStore.store.edit {
-            it[LAST_REQUESTED] = policy.stableId
-            it[LAST_REQUESTED_AT] = nowMillis
-            if (persistent) {
-                it[LAST_PERSISTENT_POLICY] = policy.stableId
-                if (policy != ChargePolicy.Unrestricted) it[PROTECTIVE_POLICY] = policy.stableId
-            }
+        policyState.update { current ->
+            current.copy(
+                lastRequested = policy.stableId,
+                lastRequestedAt = nowMillis,
+                lastPersistent = if (persistent) policy.stableId else current.lastPersistent,
+                protective = if (persistent && policy != ChargePolicy.Unrestricted) {
+                    policy.stableId
+                } else {
+                    current.protective
+                },
+            )
         }
     }
 
-    suspend fun lastRequestedNow(): ChargePolicy? = lastRequested.first()
+    suspend fun lastRequestedNow(): ChargePolicy? = ChargePolicy.fromStableId(policyState.value().lastRequested)
 
-    suspend fun lastRequestedAtNow(): Long = lastRequestedAt.first()
+    suspend fun lastRequestedAtNow(): Long = policyState.value().lastRequestedAt
 
-    suspend fun protectivePolicyNow(): ChargePolicy = protectivePolicy.first()
+    suspend fun protectivePolicyNow(): ChargePolicy = policyState.value().protectivePolicy()
 
-    suspend fun lastPersistentPolicyNow(): ChargePolicy? = lastPersistentPolicy.first()
-
-    private companion object {
-        val LAST_REQUESTED = stringPreferencesKey("policy.last_requested")
-        val LAST_REQUESTED_AT = longPreferencesKey("policy.last_requested_at")
-        val PROTECTIVE_POLICY = stringPreferencesKey("policy.protective")
-        val LAST_PERSISTENT_POLICY = stringPreferencesKey("policy.last_persistent")
-    }
+    suspend fun lastPersistentPolicyNow(): ChargePolicy? =
+        ChargePolicy.fromStableId(policyState.value().lastPersistent)
 }
+
+/**
+ * Unrestricted is never a protective baseline, and neither is an unreadable value — both fall back to
+ * the 80 % limit rather than leaving the battery uncapped.
+ */
+private fun PolicyState.protectivePolicy(): ChargePolicy =
+    ChargePolicy.fromStableId(protective)?.takeUnless { it == ChargePolicy.Unrestricted }
+        ?: ChargePolicy.FixedLimit(80)

app/src/main/java/eu/darken/amply/charging/core/access/AutoWssGrantCoordinator.kt

@@ -49,7 +49,7 @@ class AutoWssGrantCoordinator @Inject constructor(
         if (!started.compareAndSet(false, true)) return
         scope.launch {
             observeAutoWssGrant(
-                inputs = autoWssGrantInputs(repository.state, onboardingSettings.isComplete),
+                inputs = autoWssGrantInputs(repository.state, onboardingSettings.isComplete.flow),
                 grantScope = scope,
             ) {
                 // The repository single-flights this call, so a concurrent manual tap or an overlapping