feat(telemetry): answer whether a route needs a charging stop

CP-042 was described in one sentence — "do I need to charge on this trip, and
in how many kilometres" — and that sentence is arithmetic, not a planner. No
charging curve, no multi-stop search, no cost function: ABRP does that and
does it better. What the car cannot tell its driver is the one thing this
answers.

It plans to a reserve rather than to zero. A forecast that says the car
arrives at 3 % is not saying the trip works, it is saying the trip works if
nothing goes wrong. The reserve is a stated number the driver can change
instead of an optimism hidden in the arithmetic.

When a stop is needed, the distance is computed at the top of the SocRate
band rather than at its middle. Being told to charge earlier than strictly
necessary costs minutes; being told to charge later costs a tow truck.

Uncertainty refuses. The band grows with distance, and past some distance
"you will arrive between 5 % and 45 %" is not a plan — a refusal is visible,
a wide answer rendered as a plan is not. The threshold is looser than the
arrival forecast's, because "you will need to charge" survives more
uncertainty than a printed arrival figure.

Refs: CP-042

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

Author: malys

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

@@ -0,0 +1,99 @@
+package com.evsuite.hardware.telemetry
+
+/**
+ * Whether a route needs a charging stop, and in how many kilometres.
+ *
+ * This is the sentence the whole project was described by — *"il faudra recharger une fois dans
+ * N km"* — and it is arithmetic, not a planner. There is deliberately no optimisation here: no
+ * charging curve, no multi-stop search, no cost function. ABRP does that and does it better;
+ * what the car cannot tell its driver is the one thing this answers.
+ *
+ * It plans to a **reserve**, never to zero. A forecast that says the car arrives at 3 % is not
+ * saying the trip works, it is saying the trip works if nothing goes wrong, and something goes
+ * wrong. The reserve is a stated number the driver can change rather than an optimism built into
+ * the arithmetic where nobody can see it.
+ *
+ * Uncertainty is the reason this refuses. [SocRate] carries a band, the band grows with
+ * distance, and past some distance "you will arrive between 5 % and 45 %" is not a plan. The
+ * refusal is visible; a wide answer rendered as a plan is not.
+ */
+object ChargeStopPlan {
+
+    /** What a careful driver keeps in the pack. Not a physical limit — a stated choice. */
+    const val DEFAULT_RESERVE_PERCENT = 10.0
+
+    /**
+     * Wider than this and the plan is refused. Looser than [ArrivalSocForecast.MAX_BAND_PERCENT]
+     * because a stop decision survives more uncertainty than a printed arrival figure: "you will
+     * need to charge" holds even when "you will arrive at 12 %" does not.
+     */
+    const val MAX_BAND_PERCENT = 25.0
+
+    sealed interface Plan {
+        /** The route completes with the reserve intact. */
+        data class NoStop(
+            val arrivalPercent: Double,
+            val marginPercent: Double,
+            val bandPercent: Double,
+        ) : Plan
+
+        /** A stop is needed, this far along the route. */
+        data class Stop(
+            val afterKm: Double,
+            val bandKm: Double,
+            val shortfallKm: Double,
+            val bandPercent: Double,
+        ) : Plan
+
+        /** Nothing worth acting on, and the reason. */
+        data class Refused(val reason: Reason) : Plan
+    }
+
+    enum class Reason { NO_CHARGE, NO_ROUTE, NO_RATE, BAND_TOO_WIDE }
+
+    /**
+     * @param socPercent charge now.
+     * @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.
+     */
+    fun of(
+        socPercent: Double?,
+        routeKm: Double?,
+        rate: SocRate?,
+        reservePercent: Double = DEFAULT_RESERVE_PERCENT,
+    ): 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
+        if (band > MAX_BAND_PERCENT) return Plan.Refused(Reason.BAND_TOO_WIDE)
+
+        val spendable = socPercent - reservePercent
+        val needed = rate.percentPerKm * routeKm
+        if (spendable >= needed) {
+            return Plan.NoStop(
+                arrivalPercent = socPercent - needed,
+                marginPercent = spendable - needed,
+                bandPercent = band,
+            )
+        }
+
+        // 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 reachKm = (spendable / worstRate).coerceAtLeast(0.0)
+        val bestRate = (rate.percentPerKm - rate.uncertaintyPercentPerKm).coerceAtLeast(1e-6)
+        val optimisticKm = spendable / bestRate
+        return Plan.Stop(
+            afterKm = reachKm,
+            bandKm = (optimisticKm - reachKm).coerceAtLeast(0.0),
+            shortfallKm = routeKm - reachKm,
+            bandPercent = band,
+        )
+    }
+}

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

@@ -0,0 +1,84 @@
+package com.evsuite.hardware.telemetry
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ChargeStopPlanTest {
+
+    private fun rate(percentPerKm: Double, uncertainty: Double) = SocRate(
+        percentPerKm = percentPerKm,
+        uncertaintyPercentPerKm = uncertainty,
+        source = SocRate.Source.TRIP_HISTORY,
+        sampleCount = 8,
+    )
+
+    @Test
+    fun `a short route on a full pack needs no stop`() {
+        val plan = ChargeStopPlan.of(90.0, 100.0, rate(0.4, 0.04))
+        assertTrue(plan is ChargeStopPlan.Plan.NoStop)
+        plan as ChargeStopPlan.Plan.NoStop
+        assertEquals(50.0, plan.arrivalPercent, 0.001)
+        assertEquals(40.0, plan.marginPercent, 0.001)
+    }
+
+    @Test
+    fun `the reserve is what makes a marginal trip need a stop`() {
+        // 100 km at 0.4 %/km spends 40 %; from 45 % that arrives at 5, under a 10 % reserve.
+        val withoutReserve = ChargeStopPlan.of(45.0, 100.0, rate(0.4, 0.02), reservePercent = 0.0)
+        val withReserve = ChargeStopPlan.of(45.0, 100.0, rate(0.4, 0.02))
+        assertTrue(withoutReserve is ChargeStopPlan.Plan.NoStop)
+        assertTrue(withReserve is ChargeStopPlan.Plan.Stop)
+    }
+
+    @Test
+    fun `the stop distance is pessimistic, not the midpoint`() {
+        // 35 % spendable at 0.4 +- 0.04 %/km: the midpoint reaches 87,5 km, the top of the
+        // band only 79,5. The driver is told the shorter one.
+        val plan = ChargeStopPlan.of(45.0, 200.0, rate(0.4, 0.04))
+        assertTrue(plan is ChargeStopPlan.Plan.Stop)
+        plan as ChargeStopPlan.Plan.Stop
+        assertEquals(79.5, plan.afterKm, 0.5)
+        assertTrue("pessimistic", plan.afterKm < 35.0 / 0.4)
+        assertEquals(200.0 - plan.afterKm, plan.shortfallKm, 0.001)
+    }
+
+    @Test
+    fun `a long route with a loose rate is refused rather than shown wide`() {
+        val plan = ChargeStopPlan.of(80.0, 600.0, rate(0.4, 0.05))
+        assertEquals(
+            ChargeStopPlan.Plan.Refused(ChargeStopPlan.Reason.BAND_TOO_WIDE),
+            plan,
+        )
+    }
+
+    @Test
+    fun `the same route with a tight rate is planned`() {
+        val plan = ChargeStopPlan.of(80.0, 600.0, rate(0.4, 0.01))
+        assertTrue(plan is ChargeStopPlan.Plan.Stop)
+    }
+
+    @Test
+    fun `missing inputs each name themselves`() {
+        assertEquals(
+            ChargeStopPlan.Plan.Refused(ChargeStopPlan.Reason.NO_CHARGE),
+            ChargeStopPlan.of(null, 100.0, rate(0.4, 0.01)),
+        )
+        assertEquals(
+            ChargeStopPlan.Plan.Refused(ChargeStopPlan.Reason.NO_ROUTE),
+            ChargeStopPlan.of(80.0, null, rate(0.4, 0.01)),
+        )
+        assertEquals(
+            ChargeStopPlan.Plan.Refused(ChargeStopPlan.Reason.NO_RATE),
+            ChargeStopPlan.of(80.0, 100.0, null),
+        )
+    }
+
+    @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))
+        assertTrue(plan is ChargeStopPlan.Plan.Stop)
+        plan as ChargeStopPlan.Plan.Stop
+        assertEquals(0.0, plan.afterKm, 0.001)
+    }
+}