Charging: Distinguish a configured policy from one that is in effect (#73)

* Charging: Distinguish a configured policy from one that is in effect

ChargeObservation.Verified conflated two claims: that a configured value
was read back, and that the charger is acting on it. The dashboard granted
its confirmed checkmark for any Verified, so an OEM mode that the ROM has
not engaged looked identical to an enforced cap.

Physically confirmed on a Xiaomi 13T (aristotle, HyperOS 2, 2026-08-16):
with Adaptive written via the shell UID and read back as Verified(Adaptive,
SHIZUKU), the phone charged 59% to 100% with no hold at any level. HyperOS
engages Intelligent charging only inside a learned overnight window, its
BaseChargeProtect_Night daemon keeping average/stddev/count preferences of
habitual charging; getNightChargingState returned 0 on all 140 evaluations
during the run. The write path is not at fault, external writes drive the
daemon identically to native UI taps.

ChargePolicy.enforcementIsConditional marks Adaptive as a policy whose
timing the OEM decides. ChargeObservation.provesPolicyInEffect() combines
it with the backend: hardware evidence settles any policy, a readback
settles only unconditional ones. It is deliberately about knowledge rather
than safety, so Unrestricted qualifies too, it is in effect exactly as
verifiably as a cap.

Presentation only. The two sites that decide whether a write landed, the
repository's `settled` computation and computeRefreshPending's sync arm,
keep clearing on any matching readback; adopting the predicate there would
spin every Xiaomi adaptive apply for the full settling window, on that
adapter's own protective default. Recovery, sessions, the native-change
guard and the reconnect gesture are untouched for the same reason.

Pixel now under-reports when the HAL reports an engaged adaptive profile,
because refreshLocked prefers a settings Verified over the hardware decode
and discards state 5. Under-claiming is the safe direction and matches how
the rest of the app fails closed; plumbing live hardware state through
would flip the card between states through a single night.

The HyperOS 2 and 3 adapters no longer share a readiness string, so
HyperOS 3 keeps the stronger hardware claim its qualification supports.

* Charging: Record the on-device verification of the conditional-policy fix

Closes the ledger's open adapter question: the HyperOS 2 protective default
stays Adaptive because the ROM offers nothing unconditional, and the honesty
lives in presentation instead. Verified on aristotle with a foss debug build
over direct WSS, including that neither policy shows a settling spinner,
which is the visible symptom of the predicate leaking into pending logic.

* Fix: Pass onOpenConditions in the conditional-policy preview

The charge-rules feature added a required callback to DashboardScreen after
this branch was cut. No textual conflict, but the merged tree stopped
compiling because the new preview passes the callback list explicitly.

* Fix: Drop onOpenConditions again after the charge-rules revert

The callback arrived on main and was reverted twenty minutes later, so the
preview needed the parameter and then needed it gone. Nothing about this
branch changed either time.

Author: d4rken

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

@@ -48,7 +48,7 @@ only after adding a row here. Detailed run narratives live in each adapter's lan
 |---|---|---|---|---|
 | Pixel | Pixel 8 `shiba` A17/API37; Pixel 9 Pro `caiman` A16/API36; Pixel 7a `lynx` A16/API36 | Full — sysfs `charging_policy` follows writes (~11–12s) | Access tiers, sessions, boot recovery, wireless hold, at-threshold, reconnect gesture, natural 100%, interrupted-session detection (7a) | 2026-07-15/-19/-20/-25 |
 | Samsung | Galaxy Tab A9+ SM-X210 One UI 8.0; Galaxy S20 FE SM-G781B One UI 4.1 | Full — sync readback + HAL enforcement | Modern multi-mode + legacy toggle, session E2E, native-change cancel, reboot recovery, R8 beta | 2026-07-21 |
-| Xiaomi | Xiaomi 13T `2306EPN60G` HyperOS 2.0 (`ro.mi.os.version.code=2`) | **Partial** — mapping/readback/session verified; the adaptive 80% hold could not be triggered, so daemon-level hardware enforcement is **not yet demonstrated** | Read matrix, both-direction writes, session at 100%, unknown-value refusal, R8 beta | 2026-07-21 |
+| Xiaomi | Xiaomi 13T `2306EPN60G` (`aristotle`) HyperOS 2.0 (`ro.mi.os.version.code=2`); 2026-08-16 re-run on `OS2.0.216.0.VMFEUXM` / Android 15 | **Partial, now characterized** — external shell-UID writes provably drive the daemon identically to native UI taps (`getProtectMode` → `checkUiModeProtect` → `setEnable`, ~80 ms, both directions, no hidden UI-only flag). The adaptive 80% hold is still **unobserved**: charged 59→100% with no plateau, `getNightChargingState` = 0 on all 140 evaluations. Cause identified — the gate is a *learned* charging-routine model (`key_ave_night_charge_start_minutes`, `…_sd`, `key_enter_night_charge_times`), not a clock window (forced clock to 02:30 did not open it). **BLOCKED on an unused test device, not FAILED.** No hardware hold signal (`Charging state`/`policy` = 0/0) | Read matrix, both-direction writes, session at 100%, unknown-value refusal, R8 beta (2026-07-21). Added 2026-08-16: external-vs-UI write-path equivalence, native UI reflects external key, learned-schedule root cause, clock-forcing negative | 2026-07-21 / 2026-08-16 |
 | OnePlus (Oplus) | OnePlus Nord CE4 Lite `CPH2621` ColorOS 15 (`ro.build.version.oplusrom=V15.0.0`) | Full — enforcement directly observable (device holds at 80%); external writes stick | Two mutually-exclusive `system` keys (Charging limit / Smart charging), WSS-only write rejected + Shizuku write succeeds for all three policies, WSS-only UX (controls disabled + Shizuku-required banner) | 2026-07-21 |
 | GrapheneOS | Pixel 9 Pro XL `komodo`, GrapheneOS 2026080501 / Android 17 — **REMOTE qualification via issue #49** (tester-run protocol, not maintainer hardware) | **Enforcement observed**: held at 80% with shield, `dumpsys battery` status=4/Charging state=4/policy=2 (limit on) vs 2/1/1 (off); shell-UID writes move the Settings UI live, **latch at plug-session start** — mid-session writes have no hardware effect until unplug→replug, replug reliably applies the current value | Key isolation (`settings list` diff → single `global battery_charge_limit` 0/1), write→UI both directions, mid-session no-op both directions, replug latch both directions, hardware signal both states. **NOT run**: app-context access tiers (WSS write from Amply, `app.grapheneos.*` package visibility), sessions/boot recovery, wireless, factory-absent key state, secondary user | 2026-08-12 |
 | Xiaomi (HyperOS 3) | Redmi Note 14 `24117RN76G` (`tanzanite`), HyperOS 3.0.302 / Android 16 (`ro.mi.os.version.code=3`) — **REMOTE qualification via issue #48** (contributor-run protocol, not maintainer hardware) | **Both-direction enforcement of EXTERNAL shell-UID writes observed** (the same write path as Amply's Shizuku service): `settings put … 2` below the cap → Battery protection active, Settings UI follows immediately, held at 80% for ~20 min under active use (voltage 4228 mV holding vs 4391 mV charging, charge counter 4283 vs 4341 corroborate; sysfs `current_now` permission-denied, so no current reading); `settings put … 0` mid-hold → charging resumes past 80 immediately. **No hardware hold signal**: `dumpsys battery` reports `status: 2` / `Charging state: 0` / `Charging policy: 0` in both states → read-back-only verification | Key mapping (three modes incl. `2` = Battery protection @80, cap fixed — no percent picker), external write → UI both directions, sustained hold, mid-hold release. Beta run 2026-08-14 added: app-context three-mode control (direct WSS), factory-absent key = Intelligent (confirmed). Session restore FAILED in that run (observer noise cancel — app bug, fixed in #65). Re-verified 2026-08-16 on v0.3.4-beta0: **session restore PASSES** — full-charge session ran to 100% and Battery protection was re-written automatically while still plugged. **NOT run**: Shizuku tier, boot recovery, wireless, R8, unplug-early restore | 2026-08-16 |
@@ -149,8 +149,60 @@ only after adding a row here. Detailed run narratives live in each adapter's lan
     (`ro.build.version.opporom`) is read, so pre-ColorOS-12 builds remain undetectable as Oplus by ROM version. A
     device with a *working* pre-15 ColorOS charge-protection feature would need a new gate signal, not a widened
     version constant — and the usual bar applies: physically observed charging cessation, not a settings mapping.
-- **Xiaomi** — adaptive hardware enforcement of external writes unconfirmed; treat the adapter as provisional until
-  the 80% hold is physically observed.
+- **Xiaomi** — **external-write handling RESOLVED (2026-08-16); the adaptive 80% hold remains unobserved and is
+  now believed UNQUALIFIABLE on an unused test device.** Split the old "adaptive enforcement unconfirmed" gap into
+  its two halves — one is now closed, the other is characterized rather than merely open.
+  - **Closed: external shell-UID writes are functionally identical to native UI taps** (Xiaomi 13T `aristotle`,
+    HyperOS 2 `OS2.0.216.0.VMFEUXM`, Android 15, maintainer hardware). Both paths produce the same daemon chain
+    with the same values, within ~80 ms of the write:
+    `ChargeProtectionUtils: getProtectMode mode:N` → `SmartChargeProtectManager: checkUiModeProtect:N` →
+    `BaseChargeProtect_: MODE_NIGHT,setEnable fromShouldWork:false,to:false,enable:{true|false}`.
+    Verified in both directions and both origins (UI tap to Charge fully / Intelligent, external
+    `settings put … 0` / `… 1`). **There is no hidden internal flag that only the Settings UI sets** — an
+    explicitly tested hypothesis, refuted. The native UI also reflects an externally-written key on next open.
+    So Amply's write mechanism is complete and correct on HyperOS 2; nothing in the adapter needs changing for
+    the write path.
+  - **Still unobserved: the hold itself.** With the key at `1` (Intelligent, written externally), the device
+    charged **59% → 100% continuously with no plateau at any level** — uniform ~4 min per point, voltage and
+    charge counter rising monotonically through 80 (4265→4293 mV, counter 3390000→3493000), `status: 2`
+    throughout. `getNightChargingState` was evaluated **140 times across the run and returned `0` every time**
+    (60 s cadence while charging). No hardware hold signal exists — `Charging state: 0` / `Charging policy: 0`
+    in all states, same as HyperOS 3.
+  - **Root cause of the non-engagement: the gate is a LEARNED schedule, not a clock window.** Strings in
+    `com.miui.securitycenter` (`com.miui.powercenter.nightcharge`) show the feature keeps a statistical model of
+    habitual overnight charging: `key_ave_night_charge_start_minutes`, `key_night_charge_start_minutes_sd`,
+    `key_night_charge_end_minutes_sd` (standard deviations), `key_enter_night_charge_times` (occurrence count),
+    `key_earliest_night_charge_end_minutes`, `key_night_charge_record`, plus four distinct
+    `isNeedNightChargeProtection return false case 1..4` rejection paths. Directly corroborated: forcing the
+    device clock to 02:30 (via `cmd time_detector set_time_state_for_tests`; shell UID lacks both `SET_TIME` and
+    `SUGGEST_MANUAL_TIME_AND_ZONE`) did **not** open the window — `isNightChargeProtectionOpen` stayed `false`.
+    Time of day alone is insufficient; the daemon wants a low-variance charging history the device does not have.
+  - **Consequence for qualification: this device cannot settle it.** The 13T is a maintainer *test* device with no
+    normal daily use, so it can never accumulate the routine the model requires. Qualifying Adaptive would need
+    either weeks of genuine (or convincingly simulated) nightly charging at a consistent time, or root to seed
+    SecurityCenter's private prefs. Record the July "could not be triggered" and this run as the **same** result
+    with a now-known cause, not as two independent failures. **Adaptive on Xiaomi is therefore BLOCKED, not
+    FAILED** — no evidence exists that it fails to hold, only that its precondition never became true.
+  - **Consequence for the adapter, RESOLVED in the same change** (see `XiaomiChargingAdapter.kt`,
+    `defaultProtectivePolicy = Adaptive`): Amply's protective policy on HyperOS 2 is a mode that, by the OEM's own
+    design, only acts inside a learned overnight window, so a device with Adaptive configured charges to 100%
+    outside it. The read was never *wrong* (the mode genuinely is configured) but "protected" overstated it. The
+    default stays — HyperOS 2 offers no unconditional protective mode — and the honesty moved to presentation:
+    `ChargePolicy.enforcementIsConditional` + `ChargeObservation.provesPolicyInEffect()` withhold the confirmed
+    checkmark from a conditional policy that only settings can vouch for. **Verified on `aristotle` itself**
+    (2026-08-16, foss debug + direct WSS): Adaptive renders with the neutral shield and "the system chooses when
+    it applies", 100% still renders with the green check and the plain readback line, and both apply without a
+    settling spinner — the last point being the visible symptom if the predicate ever leaks into pending logic.
+    Note HyperOS blocks adb installs behind an on-device "Install via USB" dialog with a 5s auto-deny, so an
+    install must be confirmed on screen while it is awake.
+  - **Dead end, do not re-investigate:** `global battery_charging_state_enforce_level` and
+    `battery_charging_state_update_delay` (both `-1` on this device) look like an enforcement lever from their
+    names — they are not. Resolved 2026-08-16 by disassembling the device's own `/system/framework/services.jar`
+    (`dexdump`): both are read by **`com.android.server.power.stats.BatteryStatsImpl$Constants`**, alongside
+    `KEY_BATTERY_CHARGED_DELAY_MS`, `KEY_MAX_HISTORY_FILES`, and `KEY_KERNEL_UID_READERS_THROTTLE_TIME`. This is
+    stock AOSP **battery-statistics bookkeeping** (when batterystats treats the device as charged, for history
+    reset), not Xiaomi charge control, and it cannot cap charging current. Never written to. Recorded here
+    specifically so the plausible-sounding name does not cost anyone a second investigation.
   - **HyperOS 3 candidate mapping (contribution report, 2026-08-07 — unqualified at the time; since landed,
     see the LANDED bullet below).** A
     Redmi Note 14 `24117RN76G` (`tanzanite`, Android 16 / SDK 36, `ro.mi.os.version.code=3`, ROM

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

@@ -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/ChargeStatus.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/adapter/XiaomiChargingAdapter.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,
         )