feat(telemetry): the road ahead goes up, and the forecast now knows

CP-031 refused a grade source because every one on offer described the
road behind the car. A route's elevation profile describes the road
ahead, which is the only kind a forecast can use — Toulouse to Alès
crosses the Cévennes, and a plan that does not know that is wrong in the
direction that strands people.

Physics, not a fit: potential energy for a stated mass, a stated
drivetrain efficiency up and a deliberately pessimistic regeneration
efficiency down, each a declared constant inside a 40 % band rather than a
parameter tuned against data this project does not have. A descent gives
charge back, always less than the same climb spent.

ChargeStopPlan folds the term into the rate, so a missing profile is null
and produces exactly the plan it produced yesterday — never a silent zero
that claims the road is flat.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: claude

lib/src/main/java/com/evsuite/hardware/telemetry/ChargeStopPlan.kt

@@ -1,5 +1,7 @@
 package com.evsuite.hardware.telemetry
 
+import kotlin.math.abs
+
 /**
  * Whether a route needs a charging stop, and in how many kilometres.
  *
@@ -56,24 +58,29 @@ object ChargeStopPlan {
      * @param routeKm the whole remaining route.
      * @param rate charge spent per kilometre, with its own uncertainty.
      * @param reservePercent the charge the driver refuses to go below.
+     * @param grade what the route's climb and descent cost, from [RouteGrade], or null when no
+     *   elevation profile came back. Null is not zero: a plan with no profile is exactly the
+     *   plan this made before profiles existed.
      */
     fun of(
         socPercent: Double?,
         routeKm: Double?,
         rate: SocRate?,
         reservePercent: Double = DEFAULT_RESERVE_PERCENT,
+        grade: RouteGrade.Cost? = null,
     ): Plan {
         if (socPercent == null || !socPercent.isFinite()) return Plan.Refused(Reason.NO_CHARGE)
         if (routeKm == null || !routeKm.isFinite() || routeKm <= 0.0) {
             return Plan.Refused(Reason.NO_ROUTE)
         }
         if (rate == null || rate.percentPerKm <= 0.0) return Plan.Refused(Reason.NO_RATE)
 
-        val band = 2.0 * rate.uncertaintyPercentPerKm * routeKm
+        val effective = withGrade(rate, routeKm, grade)
+        val band = 2.0 * effective.uncertaintyPercentPerKm * routeKm
         if (band > MAX_BAND_PERCENT) return Plan.Refused(Reason.BAND_TOO_WIDE)
 
         val spendable = socPercent - reservePercent
-        val needed = rate.percentPerKm * routeKm
+        val needed = effective.percentPerKm * routeKm
         if (spendable >= needed) {
             return Plan.NoStop(
                 arrivalPercent = socPercent - needed,
@@ -85,9 +92,10 @@ object ChargeStopPlan {
         // Pessimistic on purpose: the distance the car reaches if it spends at the top of the
         // band. Being told to charge earlier than strictly necessary is a cost of minutes;
         // being told to charge later is a cost of a tow truck.
-        val worstRate = rate.percentPerKm + rate.uncertaintyPercentPerKm
+        val worstRate = effective.percentPerKm + effective.uncertaintyPercentPerKm
         val reachKm = (spendable / worstRate).coerceAtLeast(0.0)
-        val bestRate = (rate.percentPerKm - rate.uncertaintyPercentPerKm).coerceAtLeast(1e-6)
+        val bestRate =
+            (effective.percentPerKm - effective.uncertaintyPercentPerKm).coerceAtLeast(1e-6)
         val optimisticKm = spendable / bestRate
         return Plan.Stop(
             afterKm = reachKm,
@@ -96,4 +104,25 @@ object ChargeStopPlan {
             bandPercent = band,
         )
     }
+
+    /**
+     * The rate with the climb folded into it, so the rest of the arithmetic never learns that
+     * grade exists.
+     *
+     * The profile is a total and not a position: the col may be at kilometre 10 or at 400 and
+     * this spreads it evenly over the route either way, which makes a stop before a late col
+     * slightly early and one after an early col slightly late. Early is the safe direction and
+     * the error is small next to the rate's own band; the upgrade, when a route needs it, is a
+     * per-segment profile rather than two cumulative numbers.
+     */
+    private fun withGrade(rate: SocRate, routeKm: Double, grade: RouteGrade.Cost?): SocRate {
+        if (grade == null) return rate
+        return rate.copy(
+            // Floored, not clamped away: a descent long enough to make the net rate negative
+            // would otherwise plan a car that gains charge for ever.
+            percentPerKm = (rate.percentPerKm + grade.percent / routeKm).coerceAtLeast(1e-6),
+            uncertaintyPercentPerKm = rate.uncertaintyPercentPerKm +
+                abs(grade.uncertaintyPercent) / routeKm,
+        )
+    }
 }

lib/src/main/java/com/evsuite/hardware/telemetry/RouteGrade.kt

@@ -0,0 +1,105 @@
+package com.evsuite.hardware.telemetry
+
+import kotlin.math.abs
+
+/**
+ * What the climbing costs, and how little of it comes back.
+ *
+ * CP-031 refused a grade source on 2026-09-01 and was right to: the vehicle publishes none, a
+ * barometric reference is unproven, power-derived grade is circular, and sampled GPS altitude
+ * describes the road *behind* the car. CP-047 changed the input rather than the argument — a
+ * route carries an elevation profile of the road **ahead**, which is the only kind a forecast
+ * can use. Toulouse to Alès crosses the Cévennes, and a forecast that does not know that is
+ * wrong in the direction that strands people.
+ *
+ * This is physics, not a fit. Potential energy for a stated mass, a stated drivetrain
+ * efficiency on the way up and a stated regeneration efficiency on the way down — every one of
+ * them a declared constant with a band, none of them a parameter tuned against data this
+ * project does not have. When there are trips over known profiles a fitted coefficient can
+ * replace it; until then a fitted number would only be a guess wearing a measurement's clothes.
+ *
+ * **Regeneration is not free.** A descent returns charge, but less than the same climb spent,
+ * because the round trip pays the drivetrain twice and pays the brakes wherever the descent is
+ * steeper than the car's drag. That asymmetry is the whole point: a route over a col comes back
+ * costing more than the flat one, never the same and never less.
+ */
+object RouteGrade {
+
+    /**
+     * The car and what is in it, in kilograms.
+     *
+     * MG4 Long Range kerb mass is about 1685 kg on the manufacturer's specification; a driver
+     * and their luggage is the rest. A specification describes the model and not this car, so
+     * this is a stated assumption carried in [RELATIVE_UNCERTAINTY] rather than a measurement —
+     * see `AGENTS.md` on specification references.
+     */
+    const val MASS_KG = 1750.0
+
+    const val GRAVITY_M_PER_S2 = 9.80665
+
+    /** Battery to wheels going up: motor, inverter and reduction gear, all of them lossy. */
+    const val DRIVETRAIN_EFFICIENCY = 0.85
+
+    /**
+     * Wheels back to battery going down, and deliberately pessimistic.
+     *
+     * The chain loses as much as the way up, and on top of that some of the descent is spent on
+     * drag rather than recovered, and a steep one reaches the regeneration limit and goes to
+     * the friction brakes. Overstating this is how a forecast promises charge that never
+     * arrives, so it is understated instead.
+     */
+    const val REGENERATION_EFFICIENCY = 0.60
+
+    /**
+     * How wrong the three constants above may be, together.
+     *
+     * Mass is a specification plus a guess at the load, and neither efficiency was measured on
+     * this car. Wide on purpose: a narrow band on numbers nobody measured is a false precision,
+     * and this one feeds a stop decision.
+     */
+    const val RELATIVE_UNCERTAINTY = 0.40
+
+    private const val JOULES_PER_KWH = 3_600_000.0
+
+    /**
+     * What the profile costs in points of charge, with its band.
+     *
+     * Negative on a route that descends more than it climbs, which is a real effect and is not
+     * clamped away — a car crossing the Alps towards the sea does arrive with more than the flat
+     * arithmetic says.
+     */
+    data class Cost(val percent: Double, val uncertaintyPercent: Double)
+
+    /**
+     * The grade term, or null when there is nothing to say.
+     *
+     * Null rather than zero, always: a silent zero grade term is a claim that the road is flat,
+     * and this cannot tell a flat road from a missing profile.
+     *
+     * @param ascentMetres cumulative climb over the route, metres.
+     * @param descentMetres cumulative descent over the route, metres.
+     * @param capacity the pack the charge is a percentage of; without it there is no bridge
+     *   between joules and state of charge.
+     */
+    fun of(
+        ascentMetres: Double?,
+        descentMetres: Double?,
+        capacity: BatteryCapacityConfig?,
+    ): Cost? {
+        if (ascentMetres == null || descentMetres == null || capacity == null) return null
+        if (!ascentMetres.isFinite() || !descentMetres.isFinite()) return null
+        if (ascentMetres < 0.0 || descentMetres < 0.0) return null
+
+        val potentialPerMetreKwh = MASS_KG * GRAVITY_M_PER_S2 / JOULES_PER_KWH
+        val spentKwh = potentialPerMetreKwh * ascentMetres / DRIVETRAIN_EFFICIENCY
+        val recoveredKwh = potentialPerMetreKwh * descentMetres * REGENERATION_EFFICIENCY
+
+        val soc = capacity.socPercentForEnergy(spentKwh - recoveredKwh)
+        val percent = soc.value ?: return null
+        if (!percent.isFinite()) return null
+        // The capacity's own band on top of the constants', added rather than combined in
+        // quadrature: they are not independent errors and the wider answer is the safe one.
+        val band = abs(percent) * RELATIVE_UNCERTAINTY + (soc.uncertainty ?: 0.0)
+        return Cost(percent, band)
+    }
+}

lib/src/test/java/com/evsuite/hardware/telemetry/ChargeStopPlanTest.kt

@@ -74,6 +74,51 @@ class ChargeStopPlanTest {
         )
     }
 
+    @Test
+    fun `a flat route plans exactly as it did before grade existed`() {
+        val flat = RouteGrade.of(0.0, 0.0, BatteryCapacityConfig(61.7, 100.0))
+        assertEquals(
+            ChargeStopPlan.of(90.0, 100.0, rate(0.4, 0.04)),
+            ChargeStopPlan.of(90.0, 100.0, rate(0.4, 0.04), grade = flat),
+        )
+    }
+
+    @Test
+    fun `a col between here and there is charge that has to be spent`() {
+        val pack = BatteryCapacityConfig(61.7, 100.0)
+        val plain = ChargeStopPlan.of(90.0, 200.0, rate(0.3, 0.02)) as ChargeStopPlan.Plan.NoStop
+        val overACol = ChargeStopPlan.of(
+            90.0, 200.0, rate(0.3, 0.02),
+            grade = RouteGrade.of(1200.0, 400.0, pack),
+        ) as ChargeStopPlan.Plan.NoStop
+
+        assertTrue("the climb costs charge", overACol.arrivalPercent < plain.arrivalPercent)
+        assertTrue("and it is less certain", overACol.bandPercent > plain.bandPercent)
+
+        // Downhill the other way, and the same route returns some of it.
+        val backDown = ChargeStopPlan.of(
+            90.0, 200.0, rate(0.3, 0.02),
+            grade = RouteGrade.of(400.0, 1200.0, pack),
+        ) as ChargeStopPlan.Plan.NoStop
+        assertTrue(backDown.arrivalPercent > plain.arrivalPercent)
+        assertTrue(
+            "the descent gives back less than the climb took",
+            backDown.arrivalPercent - plain.arrivalPercent <
+                plain.arrivalPercent - overACol.arrivalPercent,
+        )
+    }
+
+    @Test
+    fun `a climb brings the stop forward rather than leaving it where it was`() {
+        val pack = BatteryCapacityConfig(61.7, 100.0)
+        val plain = ChargeStopPlan.of(45.0, 300.0, rate(0.4, 0.02)) as ChargeStopPlan.Plan.Stop
+        val overACol = ChargeStopPlan.of(
+            45.0, 300.0, rate(0.4, 0.02),
+            grade = RouteGrade.of(1200.0, 0.0, pack),
+        ) as ChargeStopPlan.Plan.Stop
+        assertTrue(overACol.afterKm < plain.afterKm)
+    }
+
     @Test
     fun `a car already below its reserve is told to stop immediately`() {
         val plan = ChargeStopPlan.of(8.0, 50.0, rate(0.4, 0.01))

lib/src/test/java/com/evsuite/hardware/telemetry/RouteGradeTest.kt

@@ -0,0 +1,64 @@
+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 RouteGradeTest {
+
+    private val pack = BatteryCapacityConfig(usableCapacityKwhWhenNew = 61.7, stateOfHealthPercent = 100.0)
+
+    @Test
+    fun `a kilometre of climb costs what the physics says, near enough to check by hand`() {
+        // 1750 kg over 1000 m is 17,2 MJ = 4,77 kWh at the wheels, 5,61 kWh from the pack at
+        // 85 %, which is 9,1 % of 61,7 kWh.
+        val cost = RouteGrade.of(1000.0, 0.0, pack)
+        assertNotNull(cost)
+        assertEquals(9.1, cost!!.percent, 0.2)
+        assertTrue("the band carries the constants", cost.uncertaintyPercent > cost.percent * 0.4)
+    }
+
+    @Test
+    fun `a flat route costs nothing, and says so as a number rather than as silence`() {
+        val cost = RouteGrade.of(0.0, 0.0, pack)
+        assertEquals(0.0, cost!!.percent, 1e-9)
+    }
+
+    @Test
+    fun `a descent returns charge, but never as much as the same climb spent`() {
+        val down = RouteGrade.of(0.0, 1000.0, pack)!!
+        val up = RouteGrade.of(1000.0, 0.0, pack)!!
+        assertTrue("a descent returns charge", down.percent < 0.0)
+        assertTrue("regeneration is not free", -down.percent < up.percent)
+    }
+
+    @Test
+    fun `a round trip over a col is not a free lunch`() {
+        val roundTrip = RouteGrade.of(1000.0, 1000.0, pack)!!
+        val climbOnly = RouteGrade.of(1000.0, 0.0, pack)!!
+        assertTrue("a col costs something both ways", roundTrip.percent > 0.0)
+        assertTrue("but less than climbing twice", roundTrip.percent < climbOnly.percent)
+        // Two thirds of a kWh per hundred metres of col, there and back. If this ever comes out
+        // at zero the efficiencies have been made equal and the arithmetic has stopped being
+        // physics.
+        assertEquals(4.4, roundTrip.percent, 0.3)
+    }
+
+    @Test
+    fun `no profile is null, and null is not a flat road`() {
+        assertNull(RouteGrade.of(null, 0.0, pack))
+        assertNull(RouteGrade.of(0.0, null, pack))
+        assertNull(RouteGrade.of(100.0, 100.0, null))
+        assertNull(RouteGrade.of(Double.NaN, 0.0, pack))
+        assertNull(RouteGrade.of(-10.0, 0.0, pack))
+    }
+
+    @Test
+    fun `a smaller pack means the same col costs a larger share of it`() {
+        val small = RouteGrade.of(1000.0, 0.0, BatteryCapacityConfig(40.0, 100.0))!!
+        val large = RouteGrade.of(1000.0, 0.0, pack)!!
+        assertTrue(small.percent > large.percent)
+    }
+}