Merge remote-tracking branch 'origin/main' into feat/charge-conditions

Author: d4rken

.claude/skills/device-qualification/SKILL.md

@@ -12,6 +12,23 @@ sealed interface ChargePolicy {
     val allowsFullCharge: Boolean
         get() = this == Unrestricted || this == PauseAtFull || (this is FixedLimit && percent >= 100)
 
+    /**
+     * Whether the OEM decides *when* this policy acts, rather than acting whenever it is configured.
+     * A conditional policy that is configured and read back proves the mode is selected — never that
+     * the battery is being protected right now. Every OEM "adaptive"/"smart"/"intelligent" mode
+     * engages only inside a learned window: a HyperOS overnight window on Xiaomi (a 13T with
+     * Intelligent charging configured and verified charged 59%→100% with no hold, 2026-08-16), and
+     * shortly before the usual unplug on Pixel/ColorOS.
+     *
+     * Consumed by [ChargeObservation.provesPolicyInEffect] for presentation only.
+     */
+    val enforcementIsConditional: Boolean
+        get() = when (this) {
+            Adaptive -> true
+            Unrestricted, PauseAtFull -> false
+            is FixedLimit -> false
+        }
+
     data object Unrestricted : ChargePolicy {
         override val stableId = "unrestricted"
         override val label = R.string.charging_policy_unrestricted_label.toCaString()

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

@@ -24,6 +24,28 @@ fun ChargingState.isSettling(now: Long): Boolean {
         obs.policy == p.target)
 }
 
+/**
+ * Whether the observed policy is what the charger is actually *doing*, as opposed to what has merely
+ * been *selected*. Note this is a statement about knowledge, not about safety: `Unrestricted` is in
+ * effect exactly as verifiably as a fixed limit, it just protects nothing.
+ *
+ * For an unconditional policy the two coincide — a fixed limit caps, and no limit charges to full,
+ * whenever configured. For a policy whose engagement the OEM decides
+ * ([ChargePolicy.enforcementIsConditional]) they come apart: a readback proves the mode is selected
+ * and nothing more, so only a [BackendKind.BATTERY_HARDWARE] reading can show it is engaged.
+ *
+ * [isSettling] asks whether the write landed; this asks whether the configuration describes reality.
+ * Those are different questions, which is why this is **presentation only**. It must never be adopted
+ * by pending, settling, recovery, session, or gesture logic: those all ask "is the configuration what
+ * we asked for?", which a conditional policy answers fully. In particular `ChargingRepository`'s
+ * `settled` computation and `computeRefreshPending`'s sync-readback arm must keep clearing on any
+ * matching readback — adopting this there would spin a Xiaomi adaptive write for the full settling
+ * window on every apply, on that adapter's own protective default.
+ */
+fun ChargeObservation.provesPolicyInEffect(): Boolean =
+    this is ChargeObservation.Verified &&
+        (backend == BackendKind.BATTERY_HARDWARE || !policy.enforcementIsConditional)
+
 /** The policy a settling request is converging on, or null when nothing is pending. Surfaces choose their own copy. */
 fun ChargingState.settlingTarget(): ChargePolicy? = pending?.target
 

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

@@ -1,6 +1,7 @@
 package eu.darken.amply.charging.core
 
 import android.content.Context
+import android.content.Intent
 import dagger.hilt.android.qualifiers.ApplicationContext
 import android.os.BatteryManager
 import eu.darken.amply.R
@@ -13,6 +14,7 @@ import eu.darken.amply.charging.core.access.shizuku.ShizukuController
 import eu.darken.amply.charging.core.adapter.AdapterRegistry
 import eu.darken.amply.charging.core.adapter.AdapterSelection
 import eu.darken.amply.charging.core.adapter.ChargingAdapter
+import eu.darken.amply.charging.core.adapter.OemChargingShortcuts
 import eu.darken.amply.charging.core.adapter.VerificationStrategy
 import eu.darken.amply.charging.core.ChargingPreferences
 import eu.darken.amply.common.ca.CaString
@@ -258,7 +260,13 @@ class ChargingRepository @Inject constructor(
         }
     }
 
-    fun nativeSettingsIntent() = registry.select().adapter?.nativeSettingsIntent(context)
+    /**
+     * Never null: a device with no adapter still gets the generic battery-settings chain. Returning null here made
+     * every unmapped device (any brand Amply carries no adapter for) land on Battery Saver, because the only caller
+     * substituted that directly — while every lab adapter deliberately prefers the battery-usage screen.
+     */
+    fun nativeSettingsIntent(): Intent = registry.select().adapter?.nativeSettingsIntent(context)
+        ?: OemChargingShortcuts.genericBatterySettings(context)
 
     fun currentAdapter(): ChargingAdapter? = registry.select().adapter
 

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

@@ -2,7 +2,6 @@ package eu.darken.amply.charging.core.adapter
 
 import android.content.Context
 import android.content.Intent
-import android.provider.Settings
 import eu.darken.amply.R
 import eu.darken.amply.charging.core.access.AccessBackend
 import eu.darken.amply.charging.core.ChargeObservation
@@ -33,17 +32,8 @@ abstract class DisabledLabAdapter : ChargingAdapter {
 
     override suspend fun apply(policy: ChargePolicy, backend: AccessBackend) = false
 
-    override fun nativeSettingsIntent(context: Context): Intent {
-        // Prefer the system battery-usage screen, which on most OEM skins is the entry point that
-        // also holds the built-in charge-protection toggle; fall back to Battery Saver settings
-        // where it isn't resolvable. Both are generic AOSP actions — no brittle OEM ComponentNames.
-        val powerUsage = Intent(Intent.ACTION_POWER_USAGE_SUMMARY).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
-        return if (powerUsage.resolveActivity(context.packageManager) != null) {
-            powerUsage
-        } else {
-            Intent(Settings.ACTION_BATTERY_SAVER_SETTINGS).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
-        }
-    }
+    override fun nativeSettingsIntent(context: Context): Intent =
+        OemChargingShortcuts.genericBatterySettings(context)
 }
 
 @Singleton

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

@@ -2,6 +2,7 @@ package eu.darken.amply.charging.core.adapter
 
 import android.content.Context
 import android.content.Intent
+import android.provider.Settings
 import eu.darken.amply.charging.core.DeviceInfo
 
 /**
@@ -25,4 +26,23 @@ object OemChargingShortcuts {
         candidate.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
         return candidate.takeIf { it.resolveActivity(context.packageManager) != null }
     }
+
+    /**
+     * The generic chain every adapter falls back to: the system battery-usage screen, which on most OEM skins is
+     * the entry point that also holds the built-in charge-protection toggle, then Battery Saver where it isn't
+     * resolvable. Both are AOSP actions — no brittle OEM ComponentNames. `POWER_USAGE_SUMMARY` visibility is
+     * declared in the manifest's `<queries>`, so it resolves on any ROM that ships the screen.
+     *
+     * A device Amply has **no adapter at all** for resolves through here too, which is the point: an unmapped
+     * device is the one most likely to need the OEM's own screen, and it used to land straight on Battery Saver
+     * because there was no adapter object to ask (`ChargingRepository.nativeSettingsIntent`).
+     */
+    fun genericBatterySettings(context: Context): Intent {
+        val powerUsage = Intent(Intent.ACTION_POWER_USAGE_SUMMARY).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        return if (powerUsage.resolveActivity(context.packageManager) != null) {
+            powerUsage
+        } else {
+            Intent(Settings.ACTION_BATTERY_SAVER_SETTINGS).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+    }
 }

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

@@ -44,6 +44,14 @@ class XiaomiChargingAdapter @Inject constructor() : ChargingAdapter {
         ChargePolicy.Unrestricted,
     )
 
+    /**
+     * The only adapter whose protective default is conditional ([ChargePolicy.enforcementIsConditional]),
+     * and unavoidably so: the HyperOS 2 key domain is `{0,1}`, so Adaptive is the sole protective mode
+     * this ROM offers. HyperOS only engages it inside a learned overnight window — a 13T with Adaptive
+     * configured and read back charged 59%→100% untouched (2026-08-16) — so the honesty burden lands on
+     * presentation, which refuses to claim active protection for it. The HyperOS 3 adapter has an
+     * unconditional mode available and defaults to `FixedLimit(80)` instead.
+     */
     override val defaultProtectivePolicy = ChargePolicy.Adaptive
     override val verification = VerificationStrategy.SYNC_READBACK
 
@@ -152,7 +160,9 @@ class XiaomiHyperOs3ChargingAdapter @Inject constructor() : ChargingAdapter {
             detail = when {
                 !matched -> R.string.adapter_detail_requires_xiaomi_hyperos3
                 !device.isSystemUser -> R.string.adapter_detail_secondary_user
-                else -> R.string.adapter_detail_xiaomi_ready
+                // Distinct from the HyperOS 2 string: Battery protection has demonstrated hardware
+                // enforcement (issue #48), so the stronger claim stays accurate here.
+                else -> R.string.adapter_detail_xiaomi_hyperos3_ready
             },
             contributionWanted = false,
         )

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

@@ -68,6 +68,7 @@ import eu.darken.amply.charging.core.access.AccessSnapshot
 import eu.darken.amply.charging.core.access.BackendStatus
 import eu.darken.amply.charging.core.isAwaitingReplug
 import eu.darken.amply.charging.core.isSettling
+import eu.darken.amply.charging.core.provesPolicyInEffect
 import eu.darken.amply.charging.core.settlingTarget
 import eu.darken.amply.common.ca.CaString
 import eu.darken.amply.common.ca.caString
@@ -441,7 +442,9 @@ private fun StatusCard(
         }
     }
     val settling = state.charging.isSettling(now)
-    val verified = observation is ChargeObservation.Verified
+    // Not "is it Verified" — a readback of a conditional policy (adaptive) proves the mode is set,
+    // not that the charger is acting on it, so it must not earn the confirmed checkmark.
+    val policyInEffect = observation.provesPolicyInEffect()
 
     // Not clickable. The card states the policy; the measurements (and the way through to them) live
     // in the charging card below. A whole-card tap here used to land on voltage and cycle counts,
@@ -461,9 +464,9 @@ private fun StatusCard(
                 )
             } else {
                 Icon(
-                    imageVector = if (verified) Icons.Default.CheckCircle else Icons.Default.Security,
+                    imageVector = if (policyInEffect) Icons.Default.CheckCircle else Icons.Default.Security,
                     contentDescription = null,
-                    tint = if (verified) Color(0xFF1A7F5A) else MaterialTheme.colorScheme.tertiary,
+                    tint = if (policyInEffect) Color(0xFF1A7F5A) else MaterialTheme.colorScheme.tertiary,
                 )
             }
             Text(
@@ -930,10 +933,16 @@ private fun ChargeObservation.title(): CaString = when (this) {
 }
 
 private fun ChargeObservation.detail(): CaString = when (this) {
-    is ChargeObservation.Verified -> if (backend == BackendKind.BATTERY_HARDWARE) {
-        R.string.dashboard_detail_hw_confirmed.toCaString()
-    } else {
-        caString {
+    // The backend placeholder stays in both readback strings: this line's job is provenance.
+    is ChargeObservation.Verified -> when {
+        backend == BackendKind.BATTERY_HARDWARE -> R.string.dashboard_detail_hw_confirmed.toCaString()
+        policy.enforcementIsConditional -> caString {
+            it.getString(
+                R.string.dashboard_detail_readback_conditional,
+                backend.name.replace('_', ' ').lowercase(),
+            )
+        }
+        else -> caString {
             it.getString(R.string.dashboard_detail_readback, backend.name.replace('_', ' ').lowercase())
         }
     }
@@ -1222,6 +1231,81 @@ private fun DashboardScreenHwUnconfirmedPreview() = PreviewWrapper {
     )
 }
 
+// The conditional-enforcement state, reproducing the real failure: a Xiaomi 13T sitting at 100% on
+// the charger with Adaptive configured and verified. HyperOS engages Intelligent charging only in a
+// learned overnight window, so the card must name the mode without claiming it is holding anything —
+// no protection checkmark, and a detail line saying the system chooses when it applies.
+@AmplyPreview
+@Composable
+private fun DashboardScreenConditionalPolicyPreview() = PreviewWrapper {
+    DashboardScreen(
+        state = DashboardUiState(
+            onboardingComplete = true,
+            batteryReadout = BatteryReadout(
+                levelPercent = 100,
+                status = android.os.BatteryManager.BATTERY_STATUS_FULL,
+                plugged = android.os.BatteryManager.BATTERY_PLUGGED_AC,
+                temperatureTenthsC = 316,
+            ),
+            charging = ChargingState(
+                device = DeviceInfo("Xiaomi", "23078RKD5G", 35, "preview"),
+                adapterName = "Xiaomi charging protection".toCaString(),
+                adapterId = "xiaomi-hyperos2-v1",
+                adapterDetail = "Setting changes apply immediately; no reconnect needed".toCaString(),
+                supportedPolicies = listOf(
+                    ChargePolicy.Adaptive,
+                    ChargePolicy.Unrestricted,
+                ),
+                defaultProtectivePolicy = ChargePolicy.Adaptive,
+                syncVerification = true,
+                controlEnabled = true,
+                access = AccessSnapshot(
+                    direct = BackendStatus(
+                        available = true,
+                        granted = true,
+                        detail = "Charge-control access granted".toCaString(),
+                    ),
+                    shizuku = BackendStatus(
+                        available = true,
+                        granted = true,
+                        detail = "Shizuku ready".toCaString(),
+                    ),
+                ),
+                observation = ChargeObservation.Verified(ChargePolicy.Adaptive, BackendKind.SHIZUKU),
+            ),
+        ),
+        adbCommand = "adb shell pm grant eu.darken.amply android.permission.WRITE_SECURE_SETTINGS",
+        onRefresh = {},
+        onSettings = {},
+        onStartFull = {},
+        onRestore = {},
+        onApply = {},
+        onQuickFullChargeChange = {},
+        onAlarmEnabledChange = {},
+        onAlarmTargetChange = {},
+        onFixNotifications = {},
+        onOpenBatteryHub = {},
+        onRetryCapture = {},
+        onPinWidget = {},
+        onAddTile = {},
+        onDismissQuickAccess = {},
+        onDismissInterruption = {},
+        onNativeSettings = {},
+        onOpenShizuku = {},
+        onAllowShizuku = {},
+        onGrantWss = {},
+        onCopyAdb = {},
+        onCopyWebUsbLink = {},
+        onPrepareSupportReport = {},
+        onCopySupportReport = {},
+        onOpenContribution = {},
+        onOpenSupportIssue = {},
+        onEmailSupport = {},
+        onHelp = {},
+        onOpenConditions = {},
+    )
+}
+
 @AmplyPreview
 @Composable
 private fun DashboardScreenApplyingPreview() = PreviewWrapper {

app/src/main/java/eu/darken/amply/main/ui/dashboard/DashboardScreen.kt

@@ -662,14 +662,22 @@ class DashboardViewModel @Inject constructor(
     }
 
     fun openNativeSettings() {
-        val intent = repository.nativeSettingsIntent() ?: Intent(Settings.ACTION_BATTERY_SAVER_SETTINGS)
-        runCatching { context.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)) }
-            .onFailure {
-                context.startActivity(
-                    Intent(Settings.ACTION_BATTERY_SAVER_SETTINGS)
-                        .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK),
-                )
-            }
+        // Resolution (including the unmapped-device fallback) lives in the repository; this only handles a
+        // launch that throws despite having resolved — resolveActivity is advisory, so an activity can be
+        // disabled or reject the launch between the check and the start.
+        val intent = repository.nativeSettingsIntent()
+        val failure = runCatching { context.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)) }
+            .exceptionOrNull() ?: return
+        log(TAG, Logging.Priority.WARN) { "Native settings ${intent.action} failed: ${failure.asLog()}" }
+        // Battery Saver is the repository's own last resort, so retrying it here would just throw again —
+        // and unguarded, that second throw escaped and took the action down with it.
+        if (intent.action == Settings.ACTION_BATTERY_SAVER_SETTINGS) return
+        runCatching {
+            context.startActivity(
+                Intent(Settings.ACTION_BATTERY_SAVER_SETTINGS)
+                    .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK),
+            )
+        }.onFailure { log(TAG, Logging.Priority.WARN) { "Battery-saver fallback failed: ${it.asLog()}" } }
     }
 
     fun openShizuku() = viewModelScope.launch {

app/src/main/java/eu/darken/amply/main/ui/dashboard/DashboardViewModel.kt

@@ -10,9 +10,19 @@ import kotlin.math.abs
  * not encode direction (charge vs discharge) — the caller derives direction from plug/charging state.
  *
  * `mV × µA = 10⁻⁹ W = 10⁻⁶ mW`, so `mW = mV × |µA| / 1_000_000`, computed in [Long] to avoid the
- * `Int` overflow that `4300 mV × 3_000_000 µA` would hit. Values outside a plausible phone/tablet
- * range are rejected as `null` because some OEM firmwares report current in the wrong unit (mA, or
- * deci-units) and would otherwise poison the session average.
+ * `Int` overflow that `4300 mV × 3_000_000 µA` would hit. Results above [MAX_PLAUSIBLE_MILLIWATTS] are
+ * rejected as `null`, which catches a grossly over-reporting firmware before it poisons the session
+ * average. It is a backstop, not a unit check: a 10× over-report of a real 4 A at 4.551 V lands at
+ * ~182 W and is accepted, as the 20 A case in the tests shows.
+ *
+ * **The opposite error is not detectable here, and deliberately is not guarded.** A firmware that
+ * reports `CURRENT_NOW` in mA where Android documents µA makes every reading 1000× too *small*: a real
+ * 4 A arrives as the integer `4000`, renders as "4 mA", and computes to 18 mW — which formats as
+ * "0.0 W". No lower bound can separate that from a legitimate end-of-charge trickle, because a phone
+ * genuinely drawing single-digit mA at 100% produces the identical value. Distinguishing them needs
+ * context this function does not have (charge level, or a second property known to be misscaled), so
+ * the fix belongs wherever that context lives, not in a magnitude clamp here. Observed on HONOR
+ * MagicOS 10 (unconfirmed) — see the HONOR entry in the device-qualification skill.
  */
 object StatsPowerCalculator {