@@ -8,6 +8,16 @@ All notable changes to this project are documented here. Format follows
 
 ### Added
 
+- **A declared battery capacity bridges kWh and state of charge.** `INFO_EV_BATTERY_CAPACITY` is
+  declared and never published on the MG4, and deriving the pack size from an energy total needs
+  battery power, which is unvalidated — so nothing could turn a model's kWh/100 km into a state
+  of charge. `BatteryCapacityConfig` takes the figure from whoever knows it. It asks for the
+  **usable** capacity, not the nameplate one, because state of charge spans the usable window
+  and the buffers at each end sit outside it: entering 64 kWh where 61.7 is usable overstates a
+  full pack by 2.2 kWh, in the optimistic direction. Everything derived from it is `ESTIMATED`
+  with a 5 % band covering a dealer's state-of-health reading and a specification figure that
+  was never a measurement of this pack. Out-of-range input is refused, never clamped.
+
 - **A recorded distance says which speed conversion produced it.** `VehicleSpeedEvidence` is the
   counterpart of `BatteryPowerEvidence` on the distance side, and it exists because the
   conversion has already been wrong once: every trip stored before the km/h fix carries a
 
@@ -0,0 +1,84 @@
+package com.evsuite.hardware.telemetry
+
+/**
+ * The pack size, as the driver declares it, because the vehicle will not say.
+ *
+ * `INFO_EV_BATTERY_CAPACITY` is declared and never published on the MG4, and deriving the
+ * capacity from an energy total needs battery power, which is itself unvalidated. Without a
+ * capacity there is no bridge between kWh and state of charge, and every energy model stops
+ * at kWh/100 km. A declared figure is the only one available, so it is taken — and labelled
+ * for exactly what it is.
+ *
+ * **Usable, not nameplate.** State of charge spans the usable window, not the gross pack: the
+ * buffers at each end are outside it. An MG4 sold as a 64 kWh car does not put 64 kWh between
+ * 0 % and 100 %, and using the nameplate figure would overstate every arrival forecast by the
+ * size of those buffers, in the optimistic direction. The field asks for the usable figure and
+ * nothing here converts one into the other, because the relationship is not published either.
+ *
+ * **Everything derived from this is [Provenance.ESTIMATED].** A dealer's state-of-health
+ * reading is itself an estimate, the usable figure is a specification rather than a
+ * measurement of this pack, and neither was taken today. [RELATIVE_UNCERTAINTY] carries that,
+ * so a value built on a declared capacity can never be drawn like a vehicle reading.
+ */
+data class BatteryCapacityConfig(
+    /** kWh between 0 % and 100 % state of charge on a healthy pack — the usable figure. */
+    val usableCapacityKwhWhenNew: Double,
+    /** State of health in percent, as measured by whoever measured it. */
+    val stateOfHealthPercent: Double,
+) {
+    /** What 100 % state of charge is worth on this pack today. */
+    val effectiveUsableKwh: Double
+        get() = usableCapacityKwhWhenNew * stateOfHealthPercent / 100.0
+
+    /**
+     * The energy behind a state of charge.
+     *
+     * @param socPercent the vehicle's own reading, 0..100.
+     */
+    fun energyAtSocKwh(socPercent: Double?): Provenanced<Double> {
+        if (socPercent == null || !socPercent.isFinite() || socPercent !in 0.0..100.0) {
+            return Provenanced.unavailable(UnavailableReason.SIGNAL_ABSENT)
+        }
+        val kwh = effectiveUsableKwh * socPercent / 100.0
+        return Provenanced.estimated(kwh, uncertainty = kwh * RELATIVE_UNCERTAINTY)
+    }
+
+    /** How many state-of-charge points an amount of energy is worth on this pack. */
+    fun socPercentForEnergy(kwh: Double?): Provenanced<Double> {
+        if (kwh == null || !kwh.isFinite() || effectiveUsableKwh <= 0.0) {
+            return Provenanced.unavailable(UnavailableReason.INSUFFICIENT_SAMPLES)
+        }
+        val soc = kwh * 100.0 / effectiveUsableKwh
+        return Provenanced.estimated(soc, uncertainty = kotlin.math.abs(soc) * RELATIVE_UNCERTAINTY)
+    }
+
+    companion object {
+        /**
+         * How wrong a declared capacity may reasonably be.
+         *
+         * It covers a dealer's state-of-health figure, a usable capacity taken from a
+         * specification rather than from this pack, and the drift since either was taken. It
+         * is deliberately not smaller: a narrow band on a number nobody measured today would
+         * be a false precision, and arrival forecasts are where that gets someone stranded.
+         */
+        const val RELATIVE_UNCERTAINTY = 0.05
+
+        private val CAPACITY_RANGE = 10.0..250.0
+        private val HEALTH_RANGE = 50.0..100.0
+
+        /**
+         * A configuration, or null when the figures are not usable.
+         *
+         * Out-of-range input is refused rather than clamped: a clamped capacity is a number
+         * the driver did not enter, silently standing in for the one they did.
+         */
+        fun of(usableCapacityKwhWhenNew: Double?, stateOfHealthPercent: Double?):
+            BatteryCapacityConfig? {
+            if (usableCapacityKwhWhenNew == null || stateOfHealthPercent == null) return null
+            if (!usableCapacityKwhWhenNew.isFinite() || !stateOfHealthPercent.isFinite()) return null
+            if (usableCapacityKwhWhenNew !in CAPACITY_RANGE) return null
+            if (stateOfHealthPercent !in HEALTH_RANGE) return null
+            return BatteryCapacityConfig(usableCapacityKwhWhenNew, stateOfHealthPercent)
+        }
+    }
+}
@@ -0,0 +1,61 @@
+package com.evsuite.hardware.telemetry
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class BatteryCapacityConfigTest {
+
+    /** The reported MG4: 64 kWh nameplate, about 61.7 kWh usable, 95 % state of health. */
+    private val mg4 = BatteryCapacityConfig.of(61.7, 95.0)!!
+
+    @Test fun `state of health scales the usable pack`() {
+        assertEquals(58.615, mg4.effectiveUsableKwh, 1e-6)
+    }
+
+    @Test fun `energy at a state of charge is an estimate with a band`() {
+        val energy = mg4.energyAtSocKwh(56.1)
+        assertEquals(Provenance.ESTIMATED, energy.provenance)
+        assertEquals(32.883, energy.value!!, 1e-3)
+        assertNotNull("a declared capacity is never drawn as a reading", energy.uncertainty)
+        assertEquals(energy.value!! * 0.05, energy.uncertainty!!, 1e-6)
+    }
+
+    @Test fun `a full pack is the effective capacity and an empty one is zero`() {
+        assertEquals(58.615, mg4.energyAtSocKwh(100.0).value!!, 1e-6)
+        assertEquals(0.0, mg4.energyAtSocKwh(0.0).value!!, 1e-9)
+    }
+
+    @Test fun `an absent or impossible state of charge is unavailable, not zero`() {
+        listOf(null, -1.0, 101.0, Double.NaN).forEach {
+            val energy = mg4.energyAtSocKwh(it)
+            assertEquals("soc=$it", Provenance.UNAVAILABLE, energy.provenance)
+            assertNull(energy.value)
+        }
+    }
+
+    @Test fun `energy converts back to state of charge with the same relative band`() {
+        val soc = mg4.socPercentForEnergy(58.615)
+        assertEquals(100.0, soc.value!!, 1e-6)
+        assertEquals(5.0, soc.uncertainty!!, 1e-6)
+    }
+
+    @Test fun `figures outside the plausible range are refused rather than clamped`() {
+        assertNull(BatteryCapacityConfig.of(0.0, 95.0))
+        assertNull(BatteryCapacityConfig.of(500.0, 95.0))
+        assertNull(BatteryCapacityConfig.of(61.7, 0.0))
+        assertNull(BatteryCapacityConfig.of(61.7, 140.0))
+        assertNull(BatteryCapacityConfig.of(null, 95.0))
+        assertNull(BatteryCapacityConfig.of(61.7, null))
+    }
+
+    @Test fun `the nameplate figure would overstate a full pack`() {
+        // Entering 64 kWh instead of the usable 61.7 inflates every forecast in the optimistic
+        // direction — which is the mistake this field's wording exists to prevent.
+        val nameplate = BatteryCapacityConfig.of(64.0, 95.0)!!
+        assertTrue(nameplate.effectiveUsableKwh > mg4.effectiveUsableKwh)
+        assertEquals(2.185, nameplate.effectiveUsableKwh - mg4.effectiveUsableKwh, 1e-3)
+    }
+}