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

package/android/src/main/java/com/brickssoft/locationtracking/engine/ElasticDistance.kt

@@ -0,0 +1,68 @@
+package com.brickssoft.locationtracking.engine
+
+import com.brickssoft.locationtracking.config.GeolocationConfig
+import com.brickssoft.locationtracking.model.TrackedLocation
+import kotlin.math.asin
+import kotlin.math.cos
+import kotlin.math.floor
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.sin
+import kotlin.math.sqrt
+
+/**
+ * Elastic distance filter: the faster the device moves, the farther apart recorded locations are.
+ *
+ * `d = distanceFilter * max(1, round(speed / 5.0) * elasticityMultiplier)`, or plain `distanceFilter` when
+ * elasticity is disabled. `round` rounds halves up; a missing, negative or non-finite speed counts as 0.
+ */
+internal object ElasticDistance {
+    /** Speed step (m/s) of the elastic multiplier. */
+    private const val SPEED_STEP_MPS = 5.0
+
+    /** The minimum distance (m) between two recorded locations at [speedMps]. */
+    fun threshold(
+        distanceFilter: Double,
+        speedMps: Float?,
+        elasticityMultiplier: Double,
+        disableElasticity: Boolean,
+    ): Double {
+        val base = if (distanceFilter.isFinite()) max(0.0, distanceFilter) else 0.0
+        if (disableElasticity) return base
+        val speed = speedMps?.toDouble()?.takeIf { it.isFinite() && it > 0.0 } ?: 0.0
+        val multiplier = if (elasticityMultiplier.isFinite()) elasticityMultiplier else 1.0
+        val factor = max(1.0, floor(speed / SPEED_STEP_MPS + 0.5) * multiplier)
+        return base * factor
+    }
+
+    /** [threshold] with the settings of [config], at the speed of [location]. */
+    fun threshold(config: GeolocationConfig, location: TrackedLocation): Double =
+        threshold(config.distanceFilter, location.speed, config.elasticityMultiplier, config.disableElasticity)
+
+    /** True if [candidate] is far enough from [lastRecorded] (or nothing was recorded yet) to be recorded. */
+    fun shouldRecord(lastRecorded: TrackedLocation?, candidate: TrackedLocation, config: GeolocationConfig): Boolean {
+        if (lastRecorded == null) return true
+        return distanceMeters(lastRecorded, candidate) >= threshold(config, candidate)
+    }
+}
+
+/** Mean Earth radius (m), IUGG. */
+private const val EARTH_RADIUS_M = 6_371_008.8
+
+/** Great-circle (haversine) distance in meters between two fixes. */
+internal fun distanceMeters(a: TrackedLocation, b: TrackedLocation): Double =
+    distanceMeters(a.latitude, a.longitude, b.latitude, b.longitude)
+
+/** Great-circle (haversine) distance in meters. */
+internal fun distanceMeters(lat1: Double, lng1: Double, lat2: Double, lng2: Double): Double {
+    val phi1 = Math.toRadians(lat1)
+    val phi2 = Math.toRadians(lat2)
+    val dPhi = Math.toRadians(lat2 - lat1)
+    val dLambda = Math.toRadians(lng2 - lng1)
+    val h = sin(dPhi / 2) * sin(dPhi / 2) + cos(phi1) * cos(phi2) * sin(dLambda / 2) * sin(dLambda / 2)
+    return 2 * EARTH_RADIUS_M * asin(min(1.0, sqrt(h)))
+}
+
+/** Horizontal accuracy (m) of a fix; unknown (non-finite or negative) counts as 0. */
+internal val TrackedLocation.accuracyMeters: Double
+    get() = accuracy.toDouble().takeIf { it.isFinite() && it > 0.0 } ?: 0.0

package/android/src/main/java/com/brickssoft/locationtracking/engine/LocationRequests.kt

@@ -0,0 +1,74 @@
+package com.brickssoft.locationtracking.engine
+
+import com.brickssoft.locationtracking.config.GeolocationConfig
+import com.brickssoft.locationtracking.config.TrackingMode
+import com.brickssoft.locationtracking.model.DesiredAccuracy
+import com.brickssoft.locationtracking.provider.LocationRequestSpec
+
+/**
+ * The continuous location request the engine wants in each situation.
+ *
+ * Requests never ask the backend to filter by distance: the engine applies the (elastic) distance filter itself,
+ * and stop detection, polygon geofences and overdue timers need fixes to keep arriving while the device does not
+ * move.
+ */
+internal object LocationRequests {
+    /**
+     * STATIONARY with the stationary region registered: PASSIVE updates, delivered at most every 30-60 s. A passive
+     * request makes the backend compute nothing; it only forwards fixes that other apps cause.
+     */
+    const val PASSIVE_INTERVAL_MS = 60_000L
+    const val PASSIVE_FASTEST_INTERVAL_MS = 30_000L
+
+    /**
+     * STATIONARY without the stationary region (registration failed, or no current anchor is known): one LOW-power
+     * fix (Wi-Fi / cell, no GPS) at most every 3 minutes.
+     */
+    const val FALLBACK_INTERVAL_MS = 180_000L
+
+    /**
+     * - LOCATION + MOVING, or [needsContinuousLocation] (inside a polygon geofence's enclosing circle):
+     *   [moving].
+     * - LOCATION + STATIONARY: the [passive] request when the `passive` argument is true (the OS watches the
+     *   stationary region, or the initial fix is still being computed by its own request), otherwise [fallback].
+     * - GEOFENCES otherwise: no request (null).
+     */
+    fun desired(
+        mode: TrackingMode,
+        isMoving: Boolean,
+        needsContinuousLocation: Boolean,
+        config: GeolocationConfig,
+        passive: Boolean,
+    ): LocationRequestSpec? = when {
+        mode == TrackingMode.LOCATION && isMoving -> moving(config)
+        needsContinuousLocation -> moving(config)
+        mode == TrackingMode.LOCATION -> if (passive) passive(config) else fallback(config)
+        else -> null
+    }
+
+    /** The configured accuracy and intervals. */
+    fun moving(config: GeolocationConfig): LocationRequestSpec = LocationRequestSpec(
+        accuracy = config.desiredAccuracy,
+        intervalMs = config.locationUpdateInterval.coerceAtLeast(0),
+        fastestIntervalMs = config.fastestLocationUpdateInterval.coerceAtLeast(0),
+        distanceFilterM = 0f,
+    )
+
+    /** PASSIVE: interval at least [PASSIVE_INTERVAL_MS], fastest interval at least [PASSIVE_FASTEST_INTERVAL_MS]. */
+    fun passive(config: GeolocationConfig): LocationRequestSpec {
+        val interval = maxOf(PASSIVE_INTERVAL_MS, config.locationUpdateInterval)
+        val fastest = minOf(interval, maxOf(PASSIVE_FASTEST_INTERVAL_MS, config.fastestLocationUpdateInterval))
+        return LocationRequestSpec(DesiredAccuracy.PASSIVE, interval, fastest, distanceFilterM = 0f)
+    }
+
+    /**
+     * LOW (or PASSIVE when that is the configured accuracy), interval and fastest interval at least
+     * [FALLBACK_INTERVAL_MS], so at most one fix per 3 minutes.
+     */
+    fun fallback(config: GeolocationConfig): LocationRequestSpec {
+        val accuracy =
+            if (config.desiredAccuracy == DesiredAccuracy.PASSIVE) DesiredAccuracy.PASSIVE else DesiredAccuracy.LOW
+        val interval = maxOf(FALLBACK_INTERVAL_MS, config.locationUpdateInterval)
+        return LocationRequestSpec(accuracy, interval, interval, distanceFilterM = 0f)
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/engine/MotionStateMachine.kt

@@ -0,0 +1,291 @@
+package com.brickssoft.locationtracking.engine
+
+import com.brickssoft.locationtracking.config.Config
+import com.brickssoft.locationtracking.model.ActivitySample
+import com.brickssoft.locationtracking.model.ActivityType
+import com.brickssoft.locationtracking.model.TrackedLocation
+import kotlin.math.max
+
+/** Motion state of the LOCATION tracking mode. */
+internal enum class MotionState {
+    STATIONARY,
+    MOVING,
+}
+
+/**
+ * The config values the [MotionStateMachine] needs.
+ *
+ * @property stopTimeoutMs time without evidence of motion after which MOVING becomes STATIONARY (at least 1 min).
+ * @property trackingAccuracyThreshold `geolocation.filter.trackingAccuracyThreshold` (m): a STATIONARY fix with a
+ *   worse accuracy never leaves STATIONARY by itself; 0 or less turns this check off.
+ */
+internal data class MotionSettings(
+    val stationaryRadius: Double = 25.0,
+    val minimumConfidence: Int = 75,
+    val motionTriggerDelayMs: Long = 0,
+    val stopTimeoutMs: Long = 5 * MINUTE_MS,
+    val disableStopDetection: Boolean = false,
+    val trackingAccuracyThreshold: Double = 100.0,
+) {
+    companion object {
+        private const val MINUTE_MS = 60_000L
+
+        fun from(config: Config): MotionSettings = MotionSettings(
+            stationaryRadius = config.geolocation.stationaryRadius.takeIf { it.isFinite() }?.coerceAtLeast(0.0) ?: 0.0,
+            minimumConfidence = config.activity.minimumActivityRecognitionConfidence,
+            motionTriggerDelayMs = config.activity.motionTriggerDelay.coerceAtLeast(0),
+            // A zero timeout would flip back to STATIONARY right after every fix; one minute is the floor.
+            stopTimeoutMs = config.geolocation.stopTimeout.coerceAtLeast(1) * MINUTE_MS,
+            disableStopDetection = config.activity.disableStopDetection,
+            trackingAccuracyThreshold =
+                config.geolocation.filter.trackingAccuracyThreshold.takeIf { it.isFinite() } ?: 0.0,
+        )
+    }
+}
+
+/** What the engine must do after feeding an input to the [MotionStateMachine]. Actions are listed in order. */
+internal sealed interface MotionAction {
+    /** The state became MOVING; [location] is the fix that triggered it, or null (activity, changePace). */
+    data class EnterMoving(val location: TrackedLocation?) : MotionAction
+
+    /** The state became STATIONARY at [location]; [automatic] is true for stop detection (not changePace). */
+    data class EnterStationary(val location: TrackedLocation?, val automatic: Boolean) : MotionAction
+
+    /** (Re)starts the stop-timeout timer; it must call [MotionStateMachine.onStopTimeout] when it fires. */
+    data class StartStopTimer(val delayMs: Long) : MotionAction
+
+    data object CancelStopTimer : MotionAction
+
+    /** Starts the motion-trigger timer; it must call [MotionStateMachine.onMotionTriggerElapsed] when it fires. */
+    data class StartMotionTrigger(val delayMs: Long) : MotionAction
+
+    data object CancelMotionTrigger : MotionAction
+}
+
+/**
+ * STATIONARY / MOVING state machine. Pure: no Android, no clock, no timers of its own; the engine runs the
+ * timers it asks for and reports back when they fire.
+ *
+ * - **STATIONARY** has an anchor (the first fix, or the location where the device stopped). It becomes MOVING
+ *   when a fix is certainly outside the stationary radius (`distance(anchor, fix) - fix accuracy >
+ *   stationaryRadius`) and its accuracy is at most `trackingAccuracyThreshold`, or when a moving activity
+ *   (walking, running, on_foot, on_bicycle, in_vehicle) at or above the confidence threshold lasts for
+ *   `motionTriggerDelay` (a confident `still` cancels the pending trigger). A fix that is certainly outside but
+ *   coarser than the threshold changes nothing. A fix that is not certainly outside and is more accurate than the
+ *   anchor replaces it. (The engine also leaves STATIONARY on the EXIT of its OS stationary region, through
+ *   [force].)
+ * - **MOVING**: stop detection (unless disabled) keeps the stop-timeout timer running. Every piece of evidence
+ *   of motion restarts it: a fix more than `max(stationaryRadius, accuracy)` from the last such fix, or a
+ *   confident moving activity. A confident `still` or a fix without displacement only makes sure it is armed,
+ *   so the device becomes STATIONARY `stopTimeout` after the last evidence of motion, even when no more
+ *   fixes arrive.
+ */
+internal class MotionStateMachine(settings: MotionSettings = MotionSettings()) {
+    var settings: MotionSettings = settings
+        private set
+
+    var state: MotionState = MotionState.STATIONARY
+        private set
+
+    val isMoving: Boolean get() = state == MotionState.MOVING
+
+    /** STATIONARY: the reference point of the stationary radius (null until the first fix). */
+    var anchor: TrackedLocation? = null
+        private set
+
+    /** MOVING: the last fix that showed displacement. */
+    var motionAnchor: TrackedLocation? = null
+        private set
+
+    var isStopTimerArmed: Boolean = false
+        private set
+
+    var isMotionTriggerArmed: Boolean = false
+        private set
+
+    /** Forgets everything and starts over in [state]. The caller cancels its timers. */
+    fun reset(state: MotionState = MotionState.STATIONARY, anchor: TrackedLocation? = null) {
+        this.state = state
+        this.anchor = if (state == MotionState.STATIONARY) anchor else null
+        motionAnchor = if (state == MotionState.MOVING) anchor else null
+        isStopTimerArmed = false
+        isMotionTriggerArmed = false
+    }
+
+    /** STATIONARY without an anchor: [location] becomes the anchor. */
+    fun offerAnchor(location: TrackedLocation?) {
+        if (state == MotionState.STATIONARY && anchor == null && location != null) anchor = location
+    }
+
+    /** STATIONARY: [location] becomes the anchor, replacing any earlier one (the fresh initial fix after start). */
+    fun setAnchor(location: TrackedLocation) {
+        if (state == MotionState.STATIONARY) anchor = location
+    }
+
+    /**
+     * Applies new settings. MOVING: may arm, cancel or restart the stop timer. STATIONARY: a pending motion
+     * trigger is cancelled when its delay changed, so the next moving activity starts over with the new delay.
+     */
+    fun updateSettings(newSettings: MotionSettings): List<MotionAction> {
+        val old = settings
+        settings = newSettings
+        if (state != MotionState.MOVING) {
+            if (!isMotionTriggerArmed || newSettings.motionTriggerDelayMs == old.motionTriggerDelayMs) return emptyList()
+            isMotionTriggerArmed = false
+            return listOf(MotionAction.CancelMotionTrigger)
+        }
+        return when {
+            newSettings.disableStopDetection -> cancelStopTimer()
+            !isStopTimerArmed || newSettings.stopTimeoutMs != old.stopTimeoutMs -> restartStopTimer()
+            else -> emptyList()
+        }
+    }
+
+    /** An accepted fix. */
+    fun onLocation(fix: TrackedLocation): List<MotionAction> = when (state) {
+        MotionState.STATIONARY -> {
+            val current = anchor
+            when {
+                current == null -> {
+                    anchor = fix
+                    emptyList()
+                }
+                isCertainlyOutside(current, fix) -> if (isAccurateEnough(fix)) enterMoving(fix) else emptyList()
+                else -> {
+                    if (fix.accuracyMeters < current.accuracyMeters) anchor = fix
+                    emptyList()
+                }
+            }
+        }
+        MotionState.MOVING -> {
+            val reference = motionAnchor
+            when {
+                reference == null -> {
+                    motionAnchor = fix
+                    ensureStopTimer()
+                }
+                distanceMeters(reference, fix) > max(settings.stationaryRadius, fix.accuracyMeters) -> {
+                    motionAnchor = fix
+                    restartStopTimer()
+                }
+                else -> ensureStopTimer()
+            }
+        }
+    }
+
+    /** An activity sample; samples below the confidence threshold are ignored. */
+    fun onActivity(sample: ActivitySample): List<MotionAction> {
+        if (sample.confidence < settings.minimumConfidence) return emptyList()
+        val moving = sample.type in MOVING_ACTIVITIES
+        val still = sample.type == ActivityType.STILL
+        return when (state) {
+            MotionState.STATIONARY -> when {
+                moving && settings.motionTriggerDelayMs <= 0 -> enterMoving(null)
+                moving && !isMotionTriggerArmed -> {
+                    isMotionTriggerArmed = true
+                    listOf(MotionAction.StartMotionTrigger(settings.motionTriggerDelayMs))
+                }
+                still && isMotionTriggerArmed -> {
+                    isMotionTriggerArmed = false
+                    listOf(MotionAction.CancelMotionTrigger)
+                }
+                else -> emptyList()
+            }
+            MotionState.MOVING -> when {
+                moving -> restartStopTimer()
+                still -> ensureStopTimer()
+                else -> emptyList()
+            }
+        }
+    }
+
+    /** The motion-trigger timer fired. */
+    fun onMotionTriggerElapsed(): List<MotionAction> {
+        val wasArmed = isMotionTriggerArmed
+        isMotionTriggerArmed = false
+        return if (wasArmed && state == MotionState.STATIONARY) enterMoving(null) else emptyList()
+    }
+
+    /** The stop-timeout timer fired; [location] (the best known fix) becomes the stationary anchor. */
+    fun onStopTimeout(location: TrackedLocation?): List<MotionAction> {
+        val wasArmed = isStopTimerArmed
+        isStopTimerArmed = false
+        return if (wasArmed && state == MotionState.MOVING) enterStationary(location, automatic = true) else emptyList()
+    }
+
+    /** `changePace`: forces a transition; [location] is the best known fix. */
+    fun force(isMoving: Boolean, location: TrackedLocation?): List<MotionAction> = when {
+        isMoving && state == MotionState.MOVING -> restartStopTimer()
+        isMoving -> enterMoving(location)
+        state == MotionState.MOVING -> enterStationary(location, automatic = false)
+        else -> emptyList()
+    }
+
+    /** True if [fix] lies outside the stationary radius around [anchor] even at the far edge of its accuracy. */
+    private fun isCertainlyOutside(anchor: TrackedLocation, fix: TrackedLocation): Boolean =
+        distanceMeters(anchor, fix) - fix.accuracyMeters > settings.stationaryRadius
+
+    /**
+     * False for a fix coarser than `trackingAccuracyThreshold`: such a fix never leaves STATIONARY by itself. (The
+     * engine's location processor already rejects such fixes; this keeps the rule of architecture round 2, §3 true
+     * for any processor.)
+     */
+    fun isAccurateEnough(fix: TrackedLocation): Boolean {
+        val threshold = settings.trackingAccuracyThreshold
+        return threshold <= 0.0 || fix.accuracyMeters <= threshold
+    }
+
+    private fun enterMoving(location: TrackedLocation?): List<MotionAction> {
+        val actions = ArrayList<MotionAction>(3)
+        if (isMotionTriggerArmed) {
+            isMotionTriggerArmed = false
+            actions += MotionAction.CancelMotionTrigger
+        }
+        state = MotionState.MOVING
+        anchor = null
+        motionAnchor = location
+        actions += MotionAction.EnterMoving(location)
+        actions += restartStopTimer()
+        return actions
+    }
+
+    private fun enterStationary(location: TrackedLocation?, automatic: Boolean): List<MotionAction> {
+        val actions = ArrayList<MotionAction>(3)
+        actions += cancelStopTimer()
+        if (isMotionTriggerArmed) {
+            isMotionTriggerArmed = false
+            actions += MotionAction.CancelMotionTrigger
+        }
+        state = MotionState.STATIONARY
+        motionAnchor = null
+        anchor = location
+        actions += MotionAction.EnterStationary(location, automatic)
+        return actions
+    }
+
+    private fun restartStopTimer(): List<MotionAction> {
+        if (settings.disableStopDetection) return emptyList()
+        isStopTimerArmed = true
+        return listOf(MotionAction.StartStopTimer(settings.stopTimeoutMs))
+    }
+
+    private fun ensureStopTimer(): List<MotionAction> =
+        if (isStopTimerArmed) emptyList() else restartStopTimer()
+
+    private fun cancelStopTimer(): List<MotionAction> {
+        if (!isStopTimerArmed) return emptyList()
+        isStopTimerArmed = false
+        return listOf(MotionAction.CancelStopTimer)
+    }
+
+    companion object {
+        /** Activities that count as motion. */
+        val MOVING_ACTIVITIES: Set<ActivityType> = setOf(
+            ActivityType.WALKING,
+            ActivityType.RUNNING,
+            ActivityType.ON_FOOT,
+            ActivityType.ON_BICYCLE,
+            ActivityType.IN_VEHICLE,
+        )
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/engine/StationaryRegion.kt

@@ -0,0 +1,41 @@
+package com.brickssoft.locationtracking.engine
+
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.provider.OsGeofence
+import kotlin.math.max
+
+/**
+ * The engine's own OS geofence while STATIONARY (architecture round 2, §3).
+ *
+ * While the device is STATIONARY the engine stops its own location requests (GPS off) and registers one circular
+ * geofence around the stationary anchor with the OS geofencing service of the selected backend. The OS reports the
+ * EXIT of that circle to `DefaultGeofenceManager`, which forwards it to the engine (`onStationaryRegionTransition`);
+ * the engine then switches to MOVING. The region is never stored, recorded or emitted as a user geofence.
+ */
+internal object StationaryRegion {
+    /**
+     * Smallest radius of the region, in meters. OS geofencing (GMS, HMS, Android proximity alerts) works with
+     * Wi-Fi and cell locations whose error is often 50-150 m, so a smaller circle would report EXIT without movement.
+     */
+    const val MIN_RADIUS_M = 150.0
+
+    /** Region radius in meters: `max(stationaryRadius, MIN_RADIUS_M)`; a non-finite radius counts as 0. */
+    fun radius(stationaryRadius: Double): Float {
+        val configured = stationaryRadius.takeIf { it.isFinite() } ?: 0.0
+        return max(configured, MIN_RADIUS_M).toFloat()
+    }
+
+    /** The region around [anchor]: EXIT only, no initial trigger, id [Constants.STATIONARY_REGION_ID]. */
+    fun around(anchor: TrackedLocation, stationaryRadius: Double): OsGeofence = OsGeofence(
+        id = Constants.STATIONARY_REGION_ID,
+        latitude = anchor.latitude,
+        longitude = anchor.longitude,
+        radius = radius(stationaryRadius),
+        onEntry = false,
+        onExit = true,
+        onDwell = false,
+        loiteringDelayMs = 0,
+        initialTriggerEntry = false,
+    )
+}

package/android/src/main/java/com/brickssoft/locationtracking/engine/TrackingEngine.kt

@@ -0,0 +1,60 @@
+package com.brickssoft.locationtracking.engine
+
+import com.brickssoft.locationtracking.config.State
+import com.brickssoft.locationtracking.provider.ActivitySink
+import com.brickssoft.locationtracking.provider.OsGeofenceTransition
+import com.brickssoft.locationtracking.provider.StationaryRegionSink
+import org.json.JSONObject
+
+/** The tracking state machine. All state changes happen on `dispatchers.engine`. */
+interface TrackingEngine : ActivitySink, StationaryRegionSink {
+    suspend fun ready(config: JSONObject?, reset: Boolean): State
+
+    suspend fun setConfig(config: JSONObject): State
+
+    suspend fun reset(config: JSONObject?): State
+
+    /** @throws com.brickssoft.locationtracking.core.TrackingException PERMISSION_DENIED if no foreground location. */
+    suspend fun start(): State
+
+    suspend fun startGeofences(): State
+
+    suspend fun stop(): State
+
+    suspend fun changePace(isMoving: Boolean)
+
+    fun state(): State
+
+    /** "restore" | "boot" | "package_replaced": cold process while enabled. */
+    suspend fun restore(reason: String)
+
+    /** Task removed. */
+    suspend fun onTerminate()
+
+    /**
+     * The foreground service could not enter the foreground after `ServiceController.start()` had returned true,
+     * for example a start from the background on Android 12+ without an exemption, or on Android 14+ with only
+     * while-in-use location permission. While tracking is enabled this stops it with the `tracking_stop` reason
+     * `service_start_failed`, so the server sees why the audit trail ends.
+     */
+    suspend fun onServiceStartFailed(error: String) = Unit
+
+    /**
+     * Tracking was enabled in a process that ended with a reboot or an app update, and `app.startOnBoot` is false, so
+     * it is not resumed. Records `tracking_stop` with [reason] (`reboot` | `package_replaced`), so the server learns why
+     * the heartbeats stopped, and clears `enabled`.
+     */
+    suspend fun endWithoutRestore(reason: String) = Unit
+
+    /**
+     * The resume notification was tapped and the service is in the foreground: resumes the session that Android refused
+     * to restore (`tracking_start` reason `resume_notification`), or stops the service if there is nothing to resume.
+     */
+    suspend fun resumeFromNotification() = Unit
+
+    /**
+     * A transition of the engine's stationary region (`Constants.STATIONARY_REGION_ID`), routed by the
+     * GeofenceManager. Round 2, unit 2 implements it (EXIT = the device left the stationary anchor). Default: ignored.
+     */
+    override suspend fun onStationaryRegionTransition(transition: OsGeofenceTransition) = Unit
+}

package/android/src/main/java/com/brickssoft/locationtracking/engine/TrackingTimers.kt

@@ -0,0 +1,90 @@
+package com.brickssoft.locationtracking.engine
+
+import com.brickssoft.locationtracking.core.Clock
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import java.util.EnumMap
+
+/** The engine's timers. */
+internal enum class TimerKind {
+    /** MOVING -> STATIONARY after `stopTimeout` without evidence of motion. */
+    STOP_TIMEOUT,
+
+    /** STATIONARY -> MOVING once a moving activity has lasted `motionTriggerDelay`. */
+    MOTION_TRIGGER,
+
+    /** `stopAfterElapsedMinutes`, measured from `trackingStartedAt`. */
+    STOP_AFTER_ELAPSED,
+}
+
+/**
+ * One-shot timers built on coroutines ([delay] in [scope]) and [Clock], without Handlers.
+ *
+ * Each timer has a deadline on the elapsed-realtime clock. A timer's action runs while holding [guard] (the
+ * engine's mutex), and only if the timer is still the current one of its kind, so a cancel or reschedule made
+ * under [guard] always wins over a timer that has already woken up. `delay()` does not advance while the CPU
+ * sleeps, so the engine also calls [fireDue] after every batch of fixes, every activity sample, every stationary-region
+ * exit and every heartbeat.
+ *
+ * Every method except the timer coroutines themselves must be called while holding [guard].
+ */
+internal class TrackingTimers(
+    private val scope: CoroutineScope,
+    private val clock: Clock,
+    private val guard: Mutex,
+) {
+    private class Entry(val deadline: Long, val action: suspend () -> Unit) {
+        var job: Job? = null
+    }
+
+    private val entries = EnumMap<TimerKind, Entry>(TimerKind::class.java)
+
+    /** (Re)schedules [kind] to run [action] (while holding the guard) after [delayMs]; a negative delay fires ASAP. */
+    fun schedule(kind: TimerKind, delayMs: Long, action: suspend () -> Unit) {
+        cancel(kind)
+        val delayMillis = delayMs.coerceAtLeast(0)
+        val entry = Entry(clock.elapsedRealtime() + delayMillis, action)
+        entries[kind] = entry
+        entry.job = scope.launch {
+            delay(delayMillis)
+            guard.withLock { fireIfCurrent(kind, entry) }
+        }
+    }
+
+    fun cancel(kind: TimerKind) {
+        entries.remove(kind)?.job?.cancel()
+    }
+
+    fun cancelAll() {
+        val all = entries.values.toList()
+        entries.clear()
+        all.forEach { it.job?.cancel() }
+    }
+
+    fun isArmed(kind: TimerKind): Boolean = entries.containsKey(kind)
+
+    /** Milliseconds until [kind] fires (0 if overdue), or null if it is not armed. */
+    fun remainingMs(kind: TimerKind): Long? =
+        entries[kind]?.let { (it.deadline - clock.elapsedRealtime()).coerceAtLeast(0) }
+
+    /** Runs every timer whose deadline has passed, in [TimerKind] order. */
+    suspend fun fireDue() {
+        for (kind in TimerKind.entries) {
+            val entry = entries[kind] ?: continue
+            if (entry.deadline > clock.elapsedRealtime()) continue
+            entry.job?.cancel()
+            fireIfCurrent(kind, entry)
+        }
+    }
+
+    private suspend fun fireIfCurrent(kind: TimerKind, entry: Entry) {
+        if (entries[kind] !== entry) return
+        // Removed before running, so the action may cancel or reschedule timers (including this kind) freely.
+        entries.remove(kind)
+        entry.action()
+    }
+}