Mileage engine
What the MileWage phone app records, which GPS fixes the track engine discards, and how the Kotlin and TypeScript implementations produce identical totals.
The track engine converts raw GPS fixes into a distance, a list of trips and a list of stops. It runs twice for every shift: once on the phone in Kotlin and once on the server in TypeScript.
Recording
| State | Behaviour |
|---|---|
| Shift running, phone moving | One GNSS fix every 5 seconds, no distance filter. Android 12 and later may batch delivery up to 15 seconds. |
| Shift running, still for 150 seconds | One fix every 60 seconds, plus the significant-motion sensor. |
| Movement detected | Returns to the 5-second cadence. Triggers: a fix outside the stillness radius, a fix at 9 km/h, or the motion sensor. |
| No shift running | Nothing is recorded. The service is stopped. |
Only fixes from the gps provider are stored. Network positions from Wi-Fi and cell towers help detect movement but are never stored or counted.
Filtering
The engine applies the same rules on the phone and on the server.
| Rule | Threshold | Effect |
|---|---|---|
| Accuracy filter | Worse than 50 m | The fix is dropped. |
| Minimum move | max(20 m, worse accuracy of the two fixes), capped at 50 m | Smaller movements from the last accepted fix are held back. |
| Speed bound | Above 42 m/s (about 150 km/h) | The jump is cut. |
| Silence | Long gap between fixes | The gap is flagged on the shift. No distance is invented. |
A held-back fix is not lost. The gate measures each step from the last accepted fix, so the next accepted fix counts the whole distance from that anchor.
The filters decide what is counted. They do not delete recorded points.
Minimum move options
Engine version 3 used a fixed 20 m minimum move. A parked phone with 35 m accuracy drifts further than that and adds distance. Version 4 scales the threshold with the reported accuracy.
The options were measured on synthetic tracks: a phone parked for 10 minutes at 30 to 50 m accuracy, and a slow city ride at 25 to 50 m accuracy.
| Minimum move | Phantom distance while parked | Loss on the slow ride |
|---|---|---|
| 20 m (version 3) | About 290 m per 10 minutes | 0.8% |
max(20 m, worse of anchor and fix) (version 4) | About 116 m | 2.5% |
max(20 m, sqrt(a² + f²)) | About 51 m | 3.9% |
max(20 m, anchor + fix) | About 8 m | 6.0% |
The reasoning is recorded in Accuracy-gated minimum move.
Stops, active miles and deadhead miles
The engine finds stops from the recorded track after the shift. The driver taps nothing during the shift.
- A shift starts as deadhead.
- A stop of about three minutes or more flips the state. The first is treated as a pickup, the next as a dropoff.
- The split is labelled "estimated" on shift pages, in the mileage log and in exports.
The estimate assumes one order at a time, so stacked orders can understate active miles. The total distance does not depend on stop detection, and the mileage deduction uses the total.
Two implementations, one result
| Property | Detail |
|---|---|
| Arithmetic | Results are whole numbers (decimetres), so rounding cannot differ between devices. |
| Trigonometry | The Kotlin port includes its own port of V8's sin, cos and atan2. |
| Versioning | Each result carries the engine's algorithm version. |
| Conformance set | packages/track-engine/conformance/fixtures.json, generated by npm run conformance:fixtures. |
| Cross-check | npm run crosscheck:engine compares the Kotlin and TypeScript outputs. |
| On-device check | Settings > Diagnostics > Mileage maths check runs the conformance set on the phone. |
The cross-check for 0.3.0 covered 2,000 and 5,000 random shifts, 900,195 maths calls and 250,000 distance pairs with 0 differences. It ran on x86-64 only.
Recalculation
The server reruns the engine when a shift ends, when fixes arrive late, and when a trip or stop is edited on the web. Trip edits, stop labels and manual trips are preserved.
A finalized shift is never recalculated.