feat(telemetry): version the distance conversion, restore the odometer

Two consequences of the 3.6x speed error, both of which outlive the fix.

A trip distance is the integral of speed, so it inherits whatever conversion
was in force when it was recorded. Every trip already stored carries a
distance 3.6 times too long and nothing in the number says so: 8.46 km for a
2.4 km route reads exactly like 8.46 km for an 8.46 km route. A model trained
on that history would learn the error.

VehicleSpeedEvidence is BatteryPowerEvidence's counterpart on the distance
side, and EnergyTripSummary.modellableDistanceKm answers only for a distance
the current conversion produced. recordedDistanceKm is untouched — a driver's
own record does not silently rewrite itself, it is simply not something a
model may train on.

And the odometer reads again. PERF_ODOMETER is declared and never published
on this car, so total mileage showed unavailable while the head unit knew it;
the navigation adapter answers, and that reading is what gave the speed error
its independent reference in the first place.

Refs: CP-003, CP-012

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

Author: malys

CHANGELOG.md

@@ -8,6 +8,20 @@ All notable changes to this project are documented here. Format follows
 
 ### Added
 
+- **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
+  distance 3.6 times too long, and nothing in the number said so — 8.46 km for a 2.4 km route
+  reads exactly like 8.46 km for an 8.46 km route. `EnergyTripSummary.modellableDistanceKm`
+  answers only for a distance produced by the conversion believed correct today, so a model
+  refuses history it cannot vouch for instead of quietly training on it. The reported distance
+  is unchanged: a driver's own record does not silently rewrite itself.
+
+- **The odometer reads again.** `PERF_ODOMETER` is declared and never published on the MG4, so
+  total mileage showed as unavailable while the head unit knew it. The navigation adapter
+  answers it, and `getOdometerKm` now falls back to it — the same reading that gave the 3.6x
+  speed error its independent reference.
+
 - **Guidance can be read, not only waited for.** The five listener callbacks are change
   notifications, so a car standing still with a guidance already running publishes nothing —
   which made a parked capture unable to tell "the adapter says nothing" from "nothing happened

lib/src/main/java/com/evsuite/hardware/EVHardware.kt

@@ -447,9 +447,21 @@ object EVHardware {
             ?.div(1_000f)
     }
 
+    /**
+     * Total mileage in km, from whichever service answers.
+     *
+     * `PERF_ODOMETER` is declared and never published on the MG4 — every read on
+     * SWI68-29958-1300R67 came back with no `CarPropertyValue` — so the odometer read as
+     * unavailable while the head unit knew it perfectly well. The navigation adapter answers
+     * it, which is how the 3.6x speed error got an independent reference at all.
+     *
+     * The adapter needs [com.evsuite.hardware.saic.SaicNav.connect] to have been called; until
+     * then it simply answers nothing, like any other unbound service.
+     */
     fun getOdometerKm(): Float? = supportedTelemetryRead {
         getFloatPropertyCPM(PROP_ODOMETER, AREA_GLOBAL)
             ?.takeIf { it.isFinite() && it >= 0f }
+            ?: com.evsuite.hardware.saic.SaicNav.totalMileageKm()?.toFloat()
     }
 
     fun getCabinTemperatureCelsius(): Float? = supportedTelemetryRead {

lib/src/main/java/com/evsuite/hardware/VehicleSpeedEvidence.kt

@@ -0,0 +1,48 @@
+package com.evsuite.hardware
+
+/**
+ * Which speed conversion produced a recorded distance.
+ *
+ * A trip distance is the integral of speed, so it inherits whatever the speed conversion was
+ * at the time — and that conversion has already been wrong once. Every trip recorded before
+ * [KMH_DIRECT_V2] on a generation that reports km/h carries a distance 3.6 times too long, and
+ * nothing in the stored number says so: 8.46 km for a 2.4 km route reads exactly like 8.46 km
+ * for an 8.46 km route.
+ *
+ * [BatteryPowerEvidence] exists for the same reason on the energy side. This is its
+ * counterpart for distance, so a model can refuse a trip whose distance it cannot vouch for
+ * instead of quietly training on it.
+ */
+data class VehicleSpeedEvidence(
+    val firmware: FirmwareInfo.Gen,
+    val conversionVersion: Int,
+) {
+    init {
+        require(firmware != FirmwareInfo.Gen.UNKNOWN) { "speed evidence names a known firmware" }
+        require(conversionVersion > 0) { "speed conversion version is positive" }
+    }
+
+    /** True when this distance was produced by the conversion currently believed correct. */
+    fun matchesCurrent(): Boolean =
+        conversionVersion == CURRENT && firmware == FirmwareInfo.getGeneration()
+
+    companion object {
+        /** `PERF_VEHICLE_SPEED` read as m/s and multiplied by 3.6, as AAOS specifies. */
+        const val MPS_TIMES_3_6_V1 = 1
+
+        /** The property read as the km/h it already carries, per generation evidence. */
+        const val KMH_DIRECT_V2 = 2
+
+        /** What a distance recorded now is produced by. */
+        const val CURRENT = KMH_DIRECT_V2
+
+        /**
+         * The evidence for a distance recorded right now, or null on an unknown firmware —
+         * where no claim about the conversion can honestly be made.
+         */
+        fun current(): VehicleSpeedEvidence? =
+            FirmwareInfo.getGeneration()
+                .takeIf { it != FirmwareInfo.Gen.UNKNOWN }
+                ?.let { VehicleSpeedEvidence(it, CURRENT) }
+    }
+}

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

@@ -2,6 +2,7 @@ package com.evsuite.hardware.telemetry
 
 import com.evsuite.hardware.BatteryPowerEvidence
 import com.evsuite.hardware.CarPropertyEvidence
+import com.evsuite.hardware.VehicleSpeedEvidence
 
 data class EnergyTripSummary(
     val startedAtMs: Long,
@@ -25,7 +26,22 @@ data class EnergyTripSummary(
     val distanceAvailable: Boolean? = null,
     /** Null for legacy or unvalidated records; models must not reuse their energy totals. */
     val batteryPowerEvidence: BatteryPowerEvidence? = null,
+    /**
+     * Which speed conversion produced [distanceKm]. Null on records written before the
+     * conversion was versioned — their distance may carry the 3.6x error and no model may
+     * train on it. See [VehicleSpeedEvidence].
+     */
+    val speedEvidence: VehicleSpeedEvidence? = null,
 ) {
+    /**
+     * The distance, only when the conversion behind it is the one believed correct today.
+     *
+     * `recordedDistanceKm` stays what the trip reported, because history is what it is and a
+     * driver's own record should not silently change. This is the one a model may use.
+     */
+    val modellableDistanceKm: Double?
+        get() = recordedDistanceKm?.takeIf { speedEvidence?.matchesCurrent() == true }
+
     val recordedDistanceKm: Double?
         get() = distanceKm.takeIf { distanceAvailable != false }
 
@@ -47,6 +63,7 @@ class EnergyTripAccumulator(
     private val startSocPercent: Float?,
     private val track: TripSampleTrack = TripSampleTrack(),
     private val batteryPowerEvidence: BatteryPowerEvidence? = null,
+    private val speedEvidence: VehicleSpeedEvidence? = VehicleSpeedEvidence.current(),
 ) {
     private var last: EnergySnapshot? = null
     private var distanceKm = 0.0
@@ -92,6 +109,7 @@ class EnergyTripAccumulator(
         consumedKwh = consumedKwh.takeIf { hasPowerInterval },
         regeneratedKwh = regeneratedKwh.takeIf { hasPowerInterval },
         distanceAvailable = hasSpeedInterval,
+        speedEvidence = speedEvidence.takeIf { hasSpeedInterval },
         batteryPowerEvidence = batteryPowerEvidence.takeIf { hasPowerInterval },
     )
 

lib/src/test/java/com/evsuite/hardware/VehicleSpeedEvidenceTest.kt

@@ -0,0 +1,45 @@
+package com.evsuite.hardware
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertThrows
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class VehicleSpeedEvidenceTest {
+
+    @Test fun `the two conversions are distinct versions`() {
+        assertEquals(1, VehicleSpeedEvidence.MPS_TIMES_3_6_V1)
+        assertEquals(2, VehicleSpeedEvidence.KMH_DIRECT_V2)
+        assertEquals(VehicleSpeedEvidence.KMH_DIRECT_V2, VehicleSpeedEvidence.CURRENT)
+    }
+
+    @Test fun `a distance from the old conversion never matches the current one`() {
+        val old = VehicleSpeedEvidence(FirmwareInfo.Gen.SWI68, VehicleSpeedEvidence.MPS_TIMES_3_6_V1)
+        assertFalse(old.matchesCurrent())
+    }
+
+    @Test fun `evidence naming an unknown firmware is refused`() {
+        assertThrows(IllegalArgumentException::class.java) {
+            VehicleSpeedEvidence(FirmwareInfo.Gen.UNKNOWN, VehicleSpeedEvidence.CURRENT)
+        }
+    }
+
+    @Test fun `a conversion version must be positive`() {
+        assertThrows(IllegalArgumentException::class.java) {
+            VehicleSpeedEvidence(FirmwareInfo.Gen.SWI68, 0)
+        }
+    }
+
+    @Test fun `an unknown firmware makes no claim rather than a wrong one`() {
+        // No vehicle in a JVM test, so the generation is UNKNOWN and current() must stay silent.
+        assertNull(VehicleSpeedEvidence.current())
+    }
+
+    @Test fun `evidence for a different firmware does not match this one`() {
+        val other = VehicleSpeedEvidence(FirmwareInfo.Gen.SWI69, VehicleSpeedEvidence.CURRENT)
+        assertFalse(other.matchesCurrent())
+        assertTrue(other.conversionVersion == VehicleSpeedEvidence.CURRENT)
+    }
+}

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

@@ -144,3 +144,36 @@ class EnergyTelemetryTest {
         override fun evidenceProbes() = probes
     }
 }
+
+class TripDistanceEvidenceTest {
+
+    private fun summary(evidence: com.evsuite.hardware.VehicleSpeedEvidence?) = EnergyTripSummary(
+        startedAtMs = 0L,
+        endedAtMs = 1_000L,
+        durationMs = 1_000L,
+        distanceKm = 8.46,
+        startSocPercent = 60f,
+        endSocPercent = 59f,
+        consumedKwh = null,
+        regeneratedKwh = null,
+        distanceAvailable = true,
+        speedEvidence = evidence,
+    )
+
+    @Test fun `a legacy distance stays reported but is not modellable`() {
+        val trip = summary(evidence = null)
+        assertEquals(8.46, trip.recordedDistanceKm!!, 1e-9)
+        assertNull("a model must not train on an unversioned distance", trip.modellableDistanceKm)
+    }
+
+    @Test fun `a distance from the 3_6x conversion is not modellable`() {
+        val trip = summary(
+            com.evsuite.hardware.VehicleSpeedEvidence(
+                com.evsuite.hardware.FirmwareInfo.Gen.SWI68,
+                com.evsuite.hardware.VehicleSpeedEvidence.MPS_TIMES_3_6_V1,
+            )
+        )
+        assertEquals(8.46, trip.recordedDistanceKm!!, 1e-9)
+        assertNull(trip.modellableDistanceKm)
+    }
+}