@bricks-soft/capacitor-location-tracking 0.0.0-stage → 8.0.0

package/android/src/main/java/com/brickssoft/locationtracking/position/DefaultPositionService.kt

@@ -0,0 +1,277 @@
+package com.brickssoft.locationtracking.position
+
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.Clock
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.device.DeviceMonitor
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.permission.PermissionManager
+import com.brickssoft.locationtracking.processing.RecordFactory
+import com.brickssoft.locationtracking.provider.LocationBackend
+import com.brickssoft.locationtracking.provider.LocationListener
+import com.brickssoft.locationtracking.provider.LocationRequestSpec
+import com.brickssoft.locationtracking.provider.ProviderFactory
+import com.brickssoft.locationtracking.record.RecordSink
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.withTimeoutOrNull
+import java.util.concurrent.ConcurrentHashMap
+import kotlin.coroutines.cancellation.CancellationException
+import kotlin.math.max
+import kotlin.math.min
+
+/**
+ * Default [PositionService].
+ *
+ * - [getCurrentPosition] requires foreground location permission and enabled location services. With
+ *   `maximumAgeMs > 0` it returns the freshest known fix (runtime or backend last location) if it is young
+ *   enough. Otherwise it samples a temporary backend request for up to `samples` fixes, stops early on a fix of
+ *   [ACCURATE_ENOUGH_M] or better, and keeps the most accurate fix. The timeout bounds the whole call; at the
+ *   timeout the best fix so far is returned, or TIMEOUT is thrown if there is none.
+ * - [watchPosition] registers one backend listener per watch id. Each fix becomes a `watch_position` record,
+ *   optionally persisted through [recordSink], and is delivered in order from [scope] (see [PositionWatch]).
+ *
+ * Mock fixes are ignored everywhere while `geolocation.filter.rejectMockLocations` is set.
+ */
+class DefaultPositionService(
+    private val providers: ProviderFactory,
+    private val configStore: ConfigStore,
+    private val permissions: PermissionManager,
+    private val device: DeviceMonitor,
+    private val recordFactory: RecordFactory,
+    private val recordSink: RecordSink,
+    private val clock: Clock,
+    private val scope: CoroutineScope,
+) : PositionService {
+    private val watches = ConcurrentHashMap<String, PositionWatch>()
+
+    override suspend fun getCurrentPosition(o: CurrentPositionOptions): Record {
+        if (!permissions.hasForegroundLocation()) {
+            throw TrackingException(ErrorCode.PERMISSION_DENIED, "Location permission is not granted")
+        }
+        if (!device.providerState().enabled) {
+            throw TrackingException(ErrorCode.LOCATION_DISABLED, "Location services are disabled")
+        }
+        val geolocation = configStore.config.value.geolocation
+        val rejectMock = geolocation.filter.rejectMockLocations
+        val timeoutMs = o.timeoutMs ?: geolocation.locationTimeout
+        val backend = providers.location()
+        val startedAt = clock.elapsedRealtime()
+
+        // The timeout covers the whole call, including the last-location lookup of the maximumAge check.
+        val location = cachedLocation(backend, o.maximumAgeMs, rejectMock, timeoutMs)
+            ?: sample(backend, o, timeoutMs - (clock.elapsedRealtime() - startedAt), rejectMock)
+            ?: throw TrackingException(ErrorCode.TIMEOUT, "No location fix within ${timeoutMs}ms")
+        val record = recordFactory.create(RecordEvent.CURRENT_POSITION, location, extras = o.extras)
+        return if (o.persist) recordSink.submit(record) else record
+    }
+
+    override fun watchPosition(id: String, o: WatchPositionOptions, callback: (Record?, TrackingException?) -> Unit) {
+        watches.remove(id)?.stop()
+        if (!permissions.hasForegroundLocation()) {
+            deliverError(id, callback, TrackingException(ErrorCode.PERMISSION_DENIED, "Location permission is not granted"))
+            return
+        }
+        if (!device.providerState().enabled) {
+            // Not an error: the backend starts delivering once location services are switched on.
+            Logger.w(TAG, "watch $id: location services are disabled")
+        }
+        val interval = o.intervalMs.coerceAtLeast(0L)
+        val spec = LocationRequestSpec(o.desiredAccuracy, interval, interval / 2, 0f)
+        val watch = PositionWatch(id, providers.location(), spec, callback) { fix -> watchRecord(fix, o) }
+        // A concurrent watchPosition() for the same id may have registered in the meantime: last one wins.
+        watches.put(id, watch)?.stop()
+        val error = watch.start(scope) ?: return
+        watches.remove(id, watch)
+        deliverError(id, callback, error)
+    }
+
+    override fun clearWatch(id: String): Boolean {
+        val watch = watches.remove(id) ?: return false
+        watch.stop()
+        return true
+    }
+
+    override fun clearAllWatches() {
+        for ((id, watch) in watches) {
+            if (watches.remove(id, watch)) watch.stop()
+        }
+    }
+
+    /**
+     * Freshest acceptable known fix no older than [maximumAgeMs], or null (always null when [maximumAgeMs] <= 0).
+     * The backend lookup takes at most [LAST_LOCATION_TIMEOUT_MS] and never longer than [timeoutMs].
+     */
+    private suspend fun cachedLocation(
+        backend: LocationBackend,
+        maximumAgeMs: Long,
+        rejectMock: Boolean,
+        timeoutMs: Long,
+    ): TrackedLocation? {
+        if (maximumAgeMs <= 0) return null
+        val known = listOfNotNull(
+            configStore.runtime.value.lastLocation,
+            lastBackendLocation(backend, min(LAST_LOCATION_TIMEOUT_MS, timeoutMs)),
+        )
+        val freshest = known.filter { accepts(it, rejectMock) }.minByOrNull { ageOf(it) } ?: return null
+        val age = ageOf(freshest)
+        if (age > maximumAgeMs) return null
+        Logger.d(TAG, "getCurrentPosition: using known fix (age ${age}ms, accuracy ${freshest.accuracy}m)")
+        return freshest
+    }
+
+    private suspend fun lastBackendLocation(backend: LocationBackend, timeoutMs: Long): TrackedLocation? = try {
+        withTimeoutOrNull(timeoutMs) { backend.getLastLocation() }
+    } catch (e: CancellationException) {
+        currentCoroutineContext().ensureActive() // the caller was cancelled: propagate
+        Logger.w(TAG, "getLastLocation was cancelled by the backend", e)
+        null
+    } catch (e: Exception) {
+        Logger.w(TAG, "getLastLocation failed", e)
+        null
+    }
+
+    /**
+     * Age of [fix] in ms: the larger of its wall-clock age and, when the fix carries an elapsed-realtime timestamp,
+     * its elapsed-realtime age. A wall-clock change therefore cannot make an old fix look fresh, and a timestamp from
+     * before a reboot only ever yields a smaller elapsed age, which the wall-clock age then dominates.
+     */
+    private fun ageOf(fix: TrackedLocation): Long {
+        val wallAge = clock.now() - fix.time
+        if (fix.elapsedRealtimeNanos <= 0L) return wallAge
+        return max(wallAge, clock.elapsedRealtime() - fix.elapsedRealtimeNanos / NANOS_PER_MS)
+    }
+
+    /**
+     * Collects fixes from a temporary backend request until [SampleCollector] is satisfied or [timeoutMs] expires,
+     * and returns the best one, or null if no acceptable fix arrived. The listener is always removed.
+     * Historical fixes computed before the request (by the elapsed-realtime clock) are ignored.
+     */
+    private suspend fun sample(
+        backend: LocationBackend,
+        o: CurrentPositionOptions,
+        timeoutMs: Long,
+        rejectMock: Boolean,
+    ): TrackedLocation? {
+        if (timeoutMs <= 0) return null
+        val collector = SampleCollector(o.samples)
+        val fixes = Channel<TrackedLocation>(Channel.UNLIMITED)
+        val listener = LocationListener { batch -> batch.forEach { fixes.trySend(it) } }
+        val spec = LocationRequestSpec(o.desiredAccuracy, SAMPLE_INTERVAL_MS, SAMPLE_FASTEST_INTERVAL_MS, 0f)
+        val requestedAt = clock.elapsedRealtime()
+        try {
+            backend.requestUpdates(spec, listener)
+            withTimeoutOrNull(timeoutMs) {
+                for (fix in fixes) {
+                    if (accepts(fix, rejectMock) && !isStaleSample(fix, requestedAt) && collector.add(fix)) break
+                }
+            }
+        } catch (e: CancellationException) {
+            currentCoroutineContext().ensureActive() // the caller was cancelled: propagate
+            throw backendError(e)
+        } catch (e: Exception) {
+            throw backendError(e)
+        } finally {
+            fixes.close()
+            removeQuietly(backend, listener)
+        }
+        val best = collector.best ?: return null
+        Logger.d(TAG, "getCurrentPosition: ${collector.count} sample(s), best accuracy ${best.accuracy}m")
+        return best
+    }
+
+    private fun isStaleSample(fix: TrackedLocation, requestedAt: Long): Boolean =
+        fix.elapsedRealtimeNanos > 0L && fix.elapsedRealtimeNanos / NANOS_PER_MS < requestedAt - STALE_SAMPLE_TOLERANCE_MS
+
+    /** Record for a watch fix, persisted if requested; null if the fix is rejected by the mock rule. */
+    private suspend fun watchRecord(fix: TrackedLocation, o: WatchPositionOptions): Record? {
+        if (!accepts(fix, configStore.config.value.geolocation.filter.rejectMockLocations)) return null
+        val record = recordFactory.create(RecordEvent.WATCH_POSITION, fix, extras = o.extras)
+        return if (o.persist) recordSink.submit(record) else record
+    }
+
+    private fun deliverError(id: String, callback: (Record?, TrackingException?) -> Unit, error: TrackingException) {
+        Logger.w(TAG, "watch $id failed: ${error.code} ${error.message}")
+        try {
+            callback(null, error)
+        } catch (e: Exception) {
+            Logger.e(TAG, "watch $id callback failed", e)
+        }
+    }
+
+    internal companion object {
+        const val TAG = "LT.Position"
+
+        /** Interval of the temporary sampling request of getCurrentPosition, ms. */
+        const val SAMPLE_INTERVAL_MS = 1_000L
+
+        /** Fastest interval of the temporary sampling request of getCurrentPosition, ms. */
+        const val SAMPLE_FASTEST_INTERVAL_MS = 500L
+
+        /** A fix at least this accurate (m) ends sampling early. */
+        const val ACCURATE_ENOUGH_M = 10f
+
+        /** Upper bound for the backend's last-location lookup of the maximumAge check, ms. */
+        const val LAST_LOCATION_TIMEOUT_MS = 5_000L
+
+        /** A sample computed more than this long before the sampling request started is historical, ms. */
+        const val STALE_SAMPLE_TOLERANCE_MS = 2_000L
+
+        private const val NANOS_PER_MS = 1_000_000L
+
+        /** False for mock fixes while [rejectMock] is set. */
+        fun accepts(fix: TrackedLocation, rejectMock: Boolean): Boolean = !(rejectMock && fix.isMock)
+
+        /** Maps a backend failure to the error reported to JS. */
+        fun backendError(e: Exception): TrackingException = when (e) {
+            is TrackingException -> e
+            is SecurityException -> TrackingException(ErrorCode.PERMISSION_DENIED, "Location permission is not granted", e)
+            else -> TrackingException(ErrorCode.UNAVAILABLE, "Location updates are unavailable: ${e.message}", e)
+        }
+
+        fun removeQuietly(backend: LocationBackend, listener: LocationListener) {
+            try {
+                backend.removeUpdates(listener)
+            } catch (e: Exception) {
+                Logger.w(TAG, "removeUpdates failed", e)
+            }
+        }
+    }
+}
+
+/**
+ * Best-of-N selection for getCurrentPosition. [add] returns true once [wanted] fixes were collected or the best
+ * fix is at least [DefaultPositionService.ACCURATE_ENOUGH_M] accurate. A fix without a usable accuracy (0, negative
+ * or NaN) ranks last; on equal accuracy the fix with the newer (or equal) fix time wins. Not thread-safe.
+ */
+internal class SampleCollector(wanted: Int) {
+    private val wanted = wanted.coerceAtLeast(1)
+
+    var best: TrackedLocation? = null
+        private set
+
+    var count = 0
+        private set
+
+    fun add(fix: TrackedLocation): Boolean {
+        count++
+        val current = best
+        val winner = if (current == null || isBetter(fix, current)) fix else current
+        best = winner
+        return count >= wanted || rank(winner) <= DefaultPositionService.ACCURATE_ENOUGH_M
+    }
+
+    private fun isBetter(fix: TrackedLocation, current: TrackedLocation): Boolean {
+        val a = rank(fix)
+        val b = rank(current)
+        return a < b || (a == b && fix.time >= current.time)
+    }
+
+    private fun rank(fix: TrackedLocation): Float = if (fix.accuracy > 0f) fix.accuracy else Float.POSITIVE_INFINITY
+}

package/android/src/main/java/com/brickssoft/locationtracking/position/PositionService.kt

@@ -0,0 +1,39 @@
+package com.brickssoft.locationtracking.position
+
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.DesiredAccuracy
+import com.brickssoft.locationtracking.model.Record
+
+/**
+ * @property timeoutMs null = `geolocation.locationTimeout`.
+ * @property extras JSON object text.
+ */
+data class CurrentPositionOptions(
+    val samples: Int = 3,
+    val timeoutMs: Long? = null,
+    val maximumAgeMs: Long = 0,
+    val desiredAccuracy: DesiredAccuracy = DesiredAccuracy.HIGH,
+    val persist: Boolean = true,
+    val extras: String? = null,
+)
+
+/** @property extras JSON object text. */
+data class WatchPositionOptions(
+    val intervalMs: Long = 1000,
+    val desiredAccuracy: DesiredAccuracy = DesiredAccuracy.HIGH,
+    val persist: Boolean = false,
+    val extras: String? = null,
+)
+
+interface PositionService {
+    /** @throws TrackingException PERMISSION_DENIED, LOCATION_DISABLED, TIMEOUT, ... */
+    suspend fun getCurrentPosition(o: CurrentPositionOptions): Record
+
+    /** [callback] receives either a record or an error, possibly many times, until [clearWatch]. */
+    fun watchPosition(id: String, o: WatchPositionOptions, callback: (Record?, TrackingException?) -> Unit)
+
+    /** Returns false if [id] was not watching. */
+    fun clearWatch(id: String): Boolean
+
+    fun clearAllWatches()
+}

package/android/src/main/java/com/brickssoft/locationtracking/position/PositionWatch.kt

@@ -0,0 +1,115 @@
+package com.brickssoft.locationtracking.position
+
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.provider.LocationBackend
+import com.brickssoft.locationtracking.provider.LocationListener
+import com.brickssoft.locationtracking.provider.LocationRequestSpec
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.launch
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * One active `watchPosition`. The backend listener only enqueues fixes; a single consumer coroutine on the
+ * given scope turns each fix into a record (through [toRecord], which may persist it) and invokes [callback],
+ * so deliveries keep the fix order and never run on the backend's thread.
+ *
+ * After [stop] returns, the listener is removed, queued fixes are dropped and [callback] is never invoked again
+ * (a callback that is running when [stop] is called finishes first); a record that is already being persisted
+ * finishes persisting. At most [BUFFER] fixes wait for the consumer; beyond that the oldest are dropped.
+ * [start] and [stop] are thread-safe and idempotent.
+ *
+ * @param toRecord returns null to skip a fix (mock rule).
+ */
+internal class PositionWatch(
+    val id: String,
+    private val backend: LocationBackend,
+    private val spec: LocationRequestSpec,
+    private val callback: (Record?, TrackingException?) -> Unit,
+    private val toRecord: suspend (TrackedLocation) -> Record?,
+) {
+    /** Guards [started], [stopped], [registered] and every [callback] invocation. */
+    private val lock = Any()
+    private val fixes = Channel<TrackedLocation>(BUFFER, BufferOverflow.DROP_OLDEST)
+    private val listener = LocationListener { batch -> batch.forEach { fixes.trySend(it) } }
+
+    @Volatile
+    private var stopped = false
+    private var started = false
+    private var registered = false
+
+    /**
+     * Starts the consumer on [scope] and registers the backend listener. Returns the error if the backend refused
+     * (the watch is then stopped and [callback] is not invoked); null on success or if already started/stopped.
+     */
+    fun start(scope: CoroutineScope): TrackingException? {
+        synchronized(lock) {
+            if (stopped || started) return null
+            started = true
+            scope.launch { consume() }
+            try {
+                backend.requestUpdates(spec, listener)
+                registered = true
+                Logger.d(DefaultPositionService.TAG, "watch $id started (${spec.accuracy.wire}, ${spec.intervalMs}ms)")
+                return null
+            } catch (e: Exception) {
+                stopped = true
+                fixes.close()
+                // A backend may have registered before failing.
+                DefaultPositionService.removeQuietly(backend, listener)
+                return DefaultPositionService.backendError(e)
+            }
+        }
+    }
+
+    /** Removes the backend listener and ends deliveries. */
+    fun stop() {
+        val wasRegistered = synchronized(lock) {
+            if (stopped) return
+            stopped = true
+            registered.also { registered = false }
+        }
+        fixes.close()
+        if (wasRegistered) DefaultPositionService.removeQuietly(backend, listener)
+        Logger.d(DefaultPositionService.TAG, "watch $id cleared")
+    }
+
+    private suspend fun consume() {
+        for (fix in fixes) {
+            if (stopped) break
+            val record = try {
+                toRecord(fix) ?: continue
+            } catch (e: Exception) {
+                // A stray CancellationException from a collaborator is a failure; our own cancellation propagates.
+                if (e is CancellationException) currentCoroutineContext().ensureActive()
+                Logger.e(DefaultPositionService.TAG, "watch $id: failed to build record", e)
+                deliver(null, TrackingException(ErrorCode.INTERNAL, "Failed to record watched position: ${e.message}", e))
+                continue
+            }
+            deliver(record, null)
+        }
+    }
+
+    private fun deliver(record: Record?, error: TrackingException?) {
+        synchronized(lock) {
+            if (stopped) return
+            try {
+                callback(record, error)
+            } catch (e: Exception) {
+                Logger.e(DefaultPositionService.TAG, "watch $id callback failed", e)
+            }
+        }
+    }
+
+    private companion object {
+        /** Fixes that may wait for the consumer (a slow sink); older ones are dropped first. */
+        const val BUFFER = 64
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/processing/DefaultLocationProcessor.kt

@@ -0,0 +1,93 @@
+package com.brickssoft.locationtracking.processing
+
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.config.LocationFilterConfig
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.TrackedLocation
+import java.util.Locale
+
+/**
+ * Location filters and optional Kalman smoothing. Reads `geolocation.filter` live from [configStore] on
+ * every fix.
+ *
+ * Rules, in order (the first match rejects):
+ * 1. invalid coordinates (non-finite, out of range, or exactly 0,0 — a known provider glitch);
+ * 2. `accuracy > trackingAccuracyThreshold` (a non-finite accuracy is also rejected);
+ * 3. a mock fix when `rejectMockLocations`;
+ * 4. a stale fix, older than the previous accepted fix;
+ * 5. an identical fix (same latitude, longitude and time as the previous accepted fix) unless
+ *    `allowIdenticalLocations`;
+ * 6. implied speed (haversine distance / time since the previous accepted fix, only when that time is > 0)
+ *    above `maxImpliedSpeed` (0 = off).
+ *
+ * Time between fixes uses the elapsed-realtime clock when both fixes carry it (see [Geo.elapsedMs]), so
+ * wall-clock changes do not affect the checks. Accepted fixes are smoothed by [KalmanFilter] when
+ * `useKalman` is set. The stale, identical and implied-speed checks compare raw fixes. Thread-safe.
+ */
+class DefaultLocationProcessor(private val configStore: ConfigStore) : LocationProcessor {
+    private val lock = Any()
+    private val kalman = KalmanFilter()
+
+    /** The previous accepted fix, before smoothing. */
+    private var lastAccepted: TrackedLocation? = null
+
+    override fun process(raw: TrackedLocation, isMoving: Boolean): FilterResult {
+        val filter = configStore.config.value.geolocation.filter
+        val result = synchronized(lock) {
+            val rejection = rejectionReason(raw, filter)
+            if (rejection != null) {
+                FilterResult.Rejected(rejection)
+            } else {
+                lastAccepted = raw
+                val location = if (filter.useKalman) {
+                    kalman.filter(raw)
+                } else {
+                    // Start fresh if smoothing is turned on again later.
+                    kalman.reset()
+                    raw
+                }
+                FilterResult.Accepted(location)
+            }
+        }
+        if (result is FilterResult.Rejected) Logger.d(TAG, "rejected fix: ${result.reason}")
+        return result
+    }
+
+    override fun reset() = synchronized(lock) {
+        lastAccepted = null
+        kalman.reset()
+    }
+
+    private fun rejectionReason(raw: TrackedLocation, filter: LocationFilterConfig): String? {
+        if (!Geo.isValid(raw.latitude, raw.longitude) || (raw.latitude == 0.0 && raw.longitude == 0.0)) {
+            return "invalid coordinates (${raw.latitude}, ${raw.longitude})"
+        }
+        val threshold = filter.trackingAccuracyThreshold
+        if (!(raw.accuracy.toDouble() <= threshold)) {
+            return "accuracy ${raw.accuracy} m > trackingAccuracyThreshold $threshold m"
+        }
+        if (raw.isMock && filter.rejectMockLocations) return "mock location"
+        val previous = lastAccepted ?: return null
+        val dtMs = Geo.elapsedMs(previous, raw)
+        if (dtMs < 0) return "stale: ${-dtMs} ms older than the previous fix"
+        if (!filter.allowIdenticalLocations &&
+            raw.latitude == previous.latitude &&
+            raw.longitude == previous.longitude &&
+            raw.time == previous.time
+        ) {
+            return "identical to the previous fix"
+        }
+        val maxSpeed = filter.maxImpliedSpeed
+        if (maxSpeed > 0 && dtMs > 0) {
+            val speed = Geo.distance(previous, raw) / (dtMs / 1000.0)
+            if (speed > maxSpeed) {
+                return "implied speed ${"%.1f".format(Locale.US, speed)} m/s > maxImpliedSpeed $maxSpeed m/s"
+            }
+        }
+        return null
+    }
+
+    private companion object {
+        const val TAG = "LT.Processor"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/processing/DefaultOdometer.kt

@@ -0,0 +1,99 @@
+package com.brickssoft.locationtracking.processing
+
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.config.RuntimeState
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.TrackedLocation
+
+/**
+ * Distance accumulator persisted in `runtime.odometer` via [ConfigStore.updateRuntime].
+ *
+ * Adds the haversine distance between consecutive fixes whose accuracy is at most
+ * `geolocation.filter.odometerAccuracyThreshold`; a less accurate fix is skipped and the previous anchor is
+ * kept. [reset] also clears the anchor; [set] keeps it.
+ *
+ * The anchor belongs to one tracking session (`runtime.trackingStartedAt`), so distance travelled while tracking
+ * was off is never counted. The first fix of a session in this process is measured from `runtime.lastLocation` if
+ * that was recorded in the same session (and is accurate enough and not newer than the fix), otherwise it only
+ * becomes the anchor:
+ * - after `start()`, `lastLocation` is the session's start position (the initial `motionchange`), which the engine
+ *   does not feed to the odometer while stationary, so the leg to the first moving fix is counted in every session;
+ * - after a cold process start (e.g. an OEM task killer and `restore`), it is where the previous process left off.
+ *
+ * [reset] clears the anchor for the rest of the current session. Thread-safe.
+ */
+class DefaultOdometer(private val configStore: ConfigStore) : Odometer {
+    private val lock = Any()
+
+    /** The last fix that passed the accuracy gate. In memory only. */
+    private var anchor: TrackedLocation? = null
+
+    /** `trackingStartedAt` of the session [anchor] belongs to; null until this process's first fix or [reset]. */
+    private var anchorSession: Long? = null
+
+    override val value: Double get() = configStore.runtime.value.odometer
+
+    override fun onLocation(location: TrackedLocation) {
+        val threshold = configStore.config.value.geolocation.filter.odometerAccuracyThreshold
+        if (!passes(location, threshold)) {
+            Logger.v(TAG, "odometer skips fix with accuracy ${location.accuracy} m (threshold $threshold m)")
+            return
+        }
+        synchronized(lock) {
+            val runtime = configStore.runtime.value
+            val session = runtime.trackingStartedAt
+            if (anchorSession != session) {
+                // Every new session is seeded, not only the first fix of the process: a later session used to start
+                // from a null anchor, which dropped the leg from its start position to its first moving fix.
+                anchor = sessionAnchor(runtime, threshold, location)
+                anchorSession = session
+            }
+            val previous = anchor
+            anchor = location
+            if (previous == null) return
+            val distance = Geo.distance(previous, location)
+            if (distance > 0) configStore.updateRuntime { it.copy(odometer = it.odometer + distance) }
+        }
+    }
+
+    /** @throws TrackingException INVALID_ARGUMENT if [value] is negative or not finite. */
+    override fun set(value: Double) {
+        if (!value.isFinite() || value < 0) {
+            throw TrackingException(ErrorCode.INVALID_ARGUMENT, "odometer must be a finite number >= 0, got $value")
+        }
+        synchronized(lock) {
+            configStore.updateRuntime { it.copy(odometer = value) }
+        }
+    }
+
+    override fun reset() {
+        synchronized(lock) {
+            anchor = null
+            // The cleared anchor belongs to the current session: its next fix is not seeded from a lastLocation that
+            // may predate the reset.
+            anchorSession = configStore.runtime.value.trackingStartedAt
+            configStore.updateRuntime { it.copy(odometer = 0.0) }
+        }
+    }
+
+    private fun passes(location: TrackedLocation, threshold: Double): Boolean =
+        location.accuracy.toDouble() <= threshold && Geo.isValid(location.latitude, location.longitude)
+
+    /**
+     * The persisted last location, if it was recorded in the current tracking session, is accurate enough and is not
+     * newer than [next] (the fix about to be measured from it).
+     */
+    private fun sessionAnchor(runtime: RuntimeState, threshold: Double, next: TrackedLocation): TrackedLocation? {
+        val session = runtime.trackingStartedAt ?: return null
+        val last = runtime.lastLocation ?: return null
+        if (!runtime.enabled || last.time < session || last.time > next.time || !passes(last, threshold)) return null
+        Logger.d(TAG, "odometer starts from the last recorded location of this session")
+        return last
+    }
+
+    private companion object {
+        const val TAG = "LT.Odometer"
+    }
+}