@@ -20,6 +20,14 @@ All notable changes to this project are documented here. Format follows
 
 ### Added
 
+- **A public post-AAOS 9 capacity signal can be tested without becoming product data.**
+  `EV_CURRENT_BATTERY_CAPACITY` describes real-time usable capacity rather than the pack's nominal
+  new capacity, but a public id does not prove that an MG4 firmware publishes it. The new
+  status-aware, firmware-branched reader is therefore internal to explicit evidence capture,
+  stays null when absent or invalid, and is carried beside — never inside — `EnergySnapshot`.
+  [The candidate review](docs/energy-signal-candidates.md) records exact AOSP provenance and the
+  negative search results for HVAC, battery-heater, accessory and cumulative energy counters.
+
 - **Three radio behaviours the library could already perform are now things a rule can ask for.**
   `srcPauseRadio`, the tuner's own play state and `startRadioActivity` were implemented and
   unreachable: the catalogue offered play, tune and station stepping, so "silence the radio"
 
@@ -0,0 +1,48 @@
+# Public energy-signal candidates
+
+Reviewed 2026-08-28 for CP-004. This review uses only public AOSP catalogues and the
+project's existing runtime read seam. It does not use proprietary artifacts or non-public
+property catalogues.
+
+## Safety and validation boundary
+
+Every entry below is read-only and starts with `validated: no`. A public property number proves
+only that AOSP assigned a number and semantics; it does not prove that an MG4 VHAL implements or
+publishes it. No candidate may enter `EnergySnapshot`, a production fallback or a stable UI until
+CP-003 records availability, unit, scale, sign and update cadence for every supported firmware
+generation. An unavailable or non-finite read stays null.
+
+## Public catalogue findings
+
+| Signal | Public declaration | Type / area / unit / mode | AOSP coverage | EVSuite disposition | validated |
+|---|---|---|---|---|---|
+| `EV_CURRENT_BATTERY_CAPACITY` (`291504909`, `0x1160030D`) | [AOSP snapshot `c80b787`](https://android.googlesource.com/platform/packages/services/Car/+/c80b787d499243d120c2738eb68e7c0520c7238d/car-lib/src/android/car/VehiclePropertyIds.java) | Float / global / Wh / on-change / read-only | Public post-AAOS 9 API; the declaration requires Car UDC with Android 13 or later | Highest-value new candidate: status-aware probe in unstable evidence capture only | no |
+| `EV_BATTERY_AVERAGE_TEMPERATURE` (`291504910`, `0x1160030E`) | [AOSP change `5b96f99`](https://android.googlesource.com/platform/packages/services/Car/+/5b96f99271e9209774a312c8f0fc1279dccf0678/car-lib/src/android/car/VehiclePropertyIds.java) | Float / global / °C / continuous / read-only | Added to the public API in December 2023 | Already read by the CP-001 baseline as nullable battery temperature; CP-004 adds no duplicate candidate | no |
+| `EV_BATTERY_INSTANTANEOUS_CHARGE_RATE` (`291504908`, `0x1160030C`) | [Android 9 AOSP snapshot `8686c86`](https://android.googlesource.com/platform/packages/services/Car/+/8686c86b38a590712412fea2dd083181aceba4f2/car-lib/src/android/car/VehiclePropertyIds.java) | Float / global / mW / continuous / read-only | Android 9 public catalogue | Existing CP-001 battery-power input; its live scale and sign still require CP-003 evidence | no |
+
+All cited files are Copyright Android Open Source Project and licensed Apache-2.0 at the cited
+commit. The review records public declarations, not copied implementation code. Vehicle coverage
+remains unknown for SWI68, SWI69, SWI131, SWI132, SWI133 and SWI165 until CP-003 runs on each one.
+
+## Explicit negative results
+
+| Requested quantity | Public catalogue result | Consequence |
+|---|---|---|
+| HVAC, compressor or PTC electrical power | No Android 9 or reviewed later public vehicle property. `HVAC_POWER_ON` is only a boolean subsystem state. | Climate energy can only be estimated from validated pack power and controlled trials. |
+| Battery-heater power | No public power or energy property found. Battery temperature is a temperature, not heater consumption. | No direct measurement candidate. |
+| DC-DC or accessory load | No public power or energy property found. | No direct measurement candidate. |
+| Cumulative battery discharge | No public cumulative counter found. `EV_BATTERY_LEVEL` is current stored energy. | Integrate validated instantaneous power, retaining uncertainty and gaps. |
+| Cumulative regeneration | No public cumulative counter found. Later regenerative-braking properties describe a state, not recovered energy. | Integrate only after CP-003 proves the power sign convention. |
+| Per-trip energy | No public per-trip energy property found. | EVSuite trip totals remain derived from validated samples. |
+
+The search deliberately stops here: sweeping arbitrary property ids would produce ambiguous data
+and broaden the runtime surface without provenance.
+
+## Probe wiring
+
+`EV_CURRENT_BATTERY_CAPACITY` is read through the same status-aware reflected
+`CarPropertyManager.getProperty` path as existing telemetry. The read is explicitly branched over
+the supported firmware generations and returns null for unknown firmware, unavailable status,
+negative values, exceptions and non-finite values. It is exposed only by
+`EnergyTelemetryReader.readEvidence()` and recorded as
+`candidate.evCurrentBatteryCapacityWh`; ordinary `read()` and `EnergySnapshot` are unchanged.
@@ -392,6 +392,7 @@ object EVHardware {
     // Standard AAOS read-only energy signals. Every access is explicitly limited to a
     // supported firmware generation; UNKNOWN stays null instead of assuming compatibility.
     private const val PROP_EV_INSTANTANEOUS_CHARGE_RATE = 0x1160030C // mW, + charge / - discharge
+    private const val PROP_EV_CURRENT_BATTERY_CAPACITY = 0x1160030D  // Wh, public post-AAOS 9 candidate
     private const val PROP_EV_CHARGE_PORT_CONNECTED = 0x1120030B
     private const val PROP_EV_BATTERY_AVG_TEMP = 0x1160030E          // °C
     private const val PROP_EV_BATTERY_LEVEL = 0x11600309             // Wh
@@ -428,6 +429,15 @@ object EVHardware {
             ?.div(1_000f)
     }
 
+    /**
+     * Probe-only public AAOS candidate; never use this as a production telemetry fallback until
+     * CP-003 validates its availability and meaning on every supported firmware generation.
+     */
+    internal fun probeCurrentBatteryCapacityWh(): Float? = supportedTelemetryRead {
+        getFloatPropertyCPM(PROP_EV_CURRENT_BATTERY_CAPACITY, AREA_GLOBAL)
+            ?.takeIf { it.isFinite() && it >= 0f }
+    }
+
     fun getStandardRangeKm(): Float? = supportedTelemetryRead {
         getFloatPropertyCPM(PROP_RANGE_REMAINING, AREA_GLOBAL)
             ?.takeIf { it.isFinite() && it >= 0f }
 
@@ -25,6 +25,8 @@ interface EnergySignalSource {
     fun parked(): Boolean?
     fun climate(): ClimateSnapshot
     fun tirePressures(): TirePressureSnapshot
+    /** Probe-only values excluded from [EnergySnapshot] and normal consumers. */
+    fun evidenceProbes(): List<TelemetryEvidenceProbe> = emptyList()
 }
 
 class EvHardwareEnergySignalSource(context: Context) : EnergySignalSource {
@@ -59,6 +61,12 @@ class EvHardwareEnergySignalSource(context: Context) : EnergySignalSource {
         rearLeftKpa = EVHardware.getTirePressureKpa(EVHardware.Wheel.REAR_LEFT),
         rearRightKpa = EVHardware.getTirePressureKpa(EVHardware.Wheel.REAR_RIGHT),
     )
+    override fun evidenceProbes() = listOf(
+        TelemetryEvidenceProbe(
+            TelemetryEvidenceRecorder.CANDIDATE_CURRENT_BATTERY_CAPACITY_WH,
+            EVHardware.probeCurrentBatteryCapacityWh()?.toDouble(),
+        )
+    )
     override fun climate() = ClimateSnapshot(
         powerOn = SaicClimate.powerOn(),
         acOn = SaicClimate.acOn(),
@@ -96,4 +104,12 @@ class EnergyTelemetryReader(private val source: EnergySignalSource) {
         climate = source.climate(),
         tirePressures = source.tirePressures(),
     )
+
+    /** Reads CP-004 candidates only when an unstable evidence capture explicitly requests them. */
+    fun readEvidence(nowMs: Long = System.currentTimeMillis()) = TelemetryEvidenceSample(
+        snapshot = read(nowMs),
+        probes = source.evidenceProbes().map { probe ->
+            probe.copy(value = probe.value?.takeIf { it.isFinite() })
+        },
+    )
 }
@@ -5,6 +5,14 @@ import com.google.gson.Gson
 /** Whether a signal is a quantity or a flag; a flag has no meaningful mean. */
 enum class SignalKind { NUMERIC, BOOLEAN }
 
+/** A read-only candidate carried beside, but never inside, the production snapshot. */
+data class TelemetryEvidenceProbe(val signal: String, val value: Double?)
+
+data class TelemetryEvidenceSample(
+    val snapshot: EnergySnapshot,
+    val probes: List<TelemetryEvidenceProbe>,
+)
+
 /**
  * What one signal did during a capture, in the terms a decision needs.
  *
@@ -109,6 +117,13 @@ class TelemetryEvidenceRecorder {
         record(CLIMATE_PASSENGER_TARGET_C, climate.passengerTargetCelsius, at)
     }
 
+    fun record(sample: TelemetryEvidenceSample) {
+        record(sample.snapshot)
+        sample.probes.forEach { probe ->
+            record(probe.signal, probe.value, sample.snapshot.timestampMs)
+        }
+    }
+
     /** For a candidate property being probed alongside the snapshot (see the CP-004 findings). */
     fun record(signal: String, value: Double?, atMs: Long) =
         accumulator(signal, SignalKind.NUMERIC).add(value, atMs)
@@ -244,6 +259,8 @@ class TelemetryEvidenceRecorder {
         const val CLIMATE_FAN_LEVEL_MAX = "climate.fanLevelMax"
         const val CLIMATE_DRIVER_TARGET_C = "climate.driverTargetCelsius"
         const val CLIMATE_PASSENGER_TARGET_C = "climate.passengerTargetCelsius"
+        const val CANDIDATE_CURRENT_BATTERY_CAPACITY_WH =
+            "candidate.evCurrentBatteryCapacityWh"
     }
 }
 
 
@@ -16,6 +16,31 @@ class EnergyTelemetryTest {
         assertEquals(18f, snapshot.batteryPowerKw)
     }
 
+    @Test fun `candidate probes exist only in the explicit evidence read`() {
+        val source = FakeSignals(soc = 80f, range = 200f, power = 18f)
+        source.probes = listOf(
+            TelemetryEvidenceProbe(
+                TelemetryEvidenceRecorder.CANDIDATE_CURRENT_BATTERY_CAPACITY_WH,
+                61_700.0,
+            )
+        )
+        val reader = EnergyTelemetryReader(source)
+
+        val normal = reader.read(41L)
+        val evidence = reader.readEvidence(42L)
+
+        assertEquals(41L, normal.timestampMs)
+        assertEquals(42L, evidence.snapshot.timestampMs)
+        assertEquals(61_700.0, evidence.probes.single().value!!, 0.0)
+    }
+
+    @Test fun `non finite candidate values fail closed`() {
+        val source = FakeSignals(soc = null, range = null, power = null)
+        source.probes = listOf(TelemetryEvidenceProbe("candidate.invalid", Double.NaN))
+
+        assertNull(EnergyTelemetryReader(source).readEvidence(42L).probes.single().value)
+    }
+
     @Test fun `trip integrates distance consumption and regeneration`() {
         val trip = EnergyTripAccumulator(0L, 80f)
         trip.add(snapshot(0L, 60f, 18f))
@@ -69,6 +94,7 @@ class EnergyTelemetryTest {
         private val range: Float?,
         private val power: Float?,
     ) : EnergySignalSource {
+        var probes: List<TelemetryEvidenceProbe> = emptyList()
         override fun firmware() = FirmwareInfo.Gen.SWI68
         override fun socPercent() = soc
         override fun rangeKm() = range
@@ -86,5 +112,6 @@ class EnergyTelemetryTest {
         override fun climate() =
             ClimateSnapshot(null, null, null, null, null, null, null, null, null)
         override fun tirePressures() = TirePressureSnapshot(null, null, null, null)
+        override fun evidenceProbes() = probes
     }
 }
@@ -150,13 +150,20 @@ class TelemetryEvidenceTest {
 
     @Test fun `a probed candidate property is recorded beside the snapshot signals`() {
         val recorder = TelemetryEvidenceRecorder()
-        recorder.record(snapshot(at = 0L, power = 1f))
-        recorder.record("candidate.hvacPowerKw", 0.8, 0L)
-        recorder.record("candidate.hvacPowerKw", null as Double?, 1_000L)
-
-        val candidate = recorder.evidence().single { it.signal == "candidate.hvacPowerKw" }
+        val name = TelemetryEvidenceRecorder.CANDIDATE_CURRENT_BATTERY_CAPACITY_WH
+        recorder.record(TelemetryEvidenceSample(
+            snapshot(at = 0L, power = 1f),
+            listOf(TelemetryEvidenceProbe(name, 61_700.0)),
+        ))
+        recorder.record(TelemetryEvidenceSample(
+            snapshot(at = 1_000L, power = 2f),
+            listOf(TelemetryEvidenceProbe(name, null)),
+        ))
+
+        val candidate = recorder.evidence().single { it.signal == name }
         assertEquals(1, candidate.samples)
         assertEquals(1, candidate.nulls)
+        assertEquals(2, recorder.capture().snapshots)
     }
 
     @Test fun `the markdown rendering names every signal and dashes what is missing`() {