feat(saic): read the remaining distance in metres on SWI68

A parked capture with guidance running answered: status 1, remaining 9788,
remaining time 25, road "Rue de la Fontaine". MapService logs that second
value as remainingMinutes, so 9788 metres is 23,5 km/h to the destination and
9788 kilometres is not a number about a car. Metres is the only reading that
survives.

remainingDistanceKm is gated per generation like every other unit here. One
observation is enough to list SWI68 and not enough to guess at anything else,
so an unlisted firmware keeps the raw value and no kilometres are claimed.

Refs: CP-040

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

Author: malys

lib/src/main/java/com/evsuite/hardware/saic/NavGuidance.kt

@@ -1,5 +1,7 @@
 package com.evsuite.hardware.saic
 
+import com.evsuite.hardware.FirmwareInfo
+
 /**
  * What the head unit's navigation stack last said about the trip in progress.
  *
@@ -31,8 +33,27 @@ data class NavGuidance(
     /** Monotonic time of the last accepted callback, or null before the first one. */
     val updatedAtElapsedMs: Long? = null,
 ) {
+    /**
+     * Remaining distance to the destination in km, when the raw value's unit is known.
+     *
+     * The adapter names no unit. A capture on 2026-09-04, SWI68-29958-1300R67, read 9788
+     * against a remaining time of 25 — and `MapService` logs that second value as
+     * `remainingMinutes`, so 9788 metres is 23,5 km/h to the destination and 9788 kilometres
+     * is not a number about a car. Metres is the only reading that survives.
+     *
+     * One observation, so this is gated per generation like every other unit here: an
+     * unlisted firmware keeps the raw value and no kilometres are claimed. A drive confirms
+     * it by comparing against the odometer span.
+     */
+    fun remainingDistanceKm(generation: FirmwareInfo.Gen): Double? =
+        remainingDistanceRaw
+            ?.takeIf { generation in REPORTS_METRES }
+            ?.let { it / 1000.0 }
     companion object {
         val EMPTY = NavGuidance()
+
+        /** Generations observed to report `getRemainingDistance` in metres. */
+        private val REPORTS_METRES = setOf(FirmwareInfo.Gen.SWI68)
     }
 }
 

lib/src/test/java/com/evsuite/hardware/saic/NavGuidanceReducerTest.kt

@@ -111,3 +111,28 @@ class TransactionCensusTest {
         assertEquals(0, census.beyondCeiling)
     }
 }
+
+class NavGuidanceDistanceUnitTest {
+
+    /** The 2026-09-04 capture: 9788 remaining, 25 minutes, "Rue de la Fontaine". */
+    private val seen = NavGuidance(remainingDistanceRaw = 9788, remainingMinutes = 25)
+
+    @Test fun `a metres generation reports kilometres`() {
+        val km = seen.remainingDistanceKm(com.evsuite.hardware.FirmwareInfo.Gen.SWI68)!!
+        assertEquals(9.788, km, 1e-9)
+        // The reading that makes it metres: 9.788 km in 25 minutes is a plausible town route.
+        assertEquals(23.5, km / (25.0 / 60.0), 0.1)
+    }
+
+    @Test fun `an unlisted generation claims no kilometres at all`() {
+        com.evsuite.hardware.FirmwareInfo.Gen.entries
+            .filterNot { it == com.evsuite.hardware.FirmwareInfo.Gen.SWI68 }
+            .forEach { assertNull("$it", seen.remainingDistanceKm(it)) }
+    }
+
+    @Test fun `no raw distance means no kilometres`() {
+        assertNull(
+            NavGuidance.EMPTY.remainingDistanceKm(com.evsuite.hardware.FirmwareInfo.Gen.SWI68)
+        )
+    }
+}