perf(osm): shrink OsmGridIndex cell size to 0.01° (~1.1 km)

Drops OsmGridIndex.CELL_E7 from 800_000 to 100_000 (CELL_DEGREES from 0.08 to 0.01), giving road-segment-scale selectivity (~1.1 km vs the old ~9 km cells) for the OSM speed-limit lookup. The packing scheme (lat in the high bits, lon in the low 24 bits) is unchanged; latitude cells now span ±9_000 (fits 16 bits) and longitude cells ±18_000 (well within the 24-bit signed slot ±8_388_607).

Every existing osm_way_cell row is keyed under the old cell size and is now stale; the paired sbase migration 31->32 drops the table and a background reindexer rebuilds it from the preserved osm_way bboxes (added in follow-up commits).

Updates OsmWayCellEntity / OsmWayCellDao KDoc to point at OsmGridIndex as the source of truth for cell-key encoding, and extends OsmGridIndexTest with invariants pinning the new size, equator/dateline/pole boundary behaviour and an end-to-end packing round-trip.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: adsamcik

osm/src/main/java/com/adsamcik/tracker/osm/io/OsmGridIndex.kt

@@ -3,19 +3,31 @@ package com.adsamcik.tracker.osm.io
 /**
  * Coarse square-degree grid used to index OSM ways for nearest-road lookup.
  *
- * The cell size is `0.08°` (E7: 800_000) — roughly 9 km at the equator and
- * still meaningful at sub-arctic latitudes. The key packs the 16-bit latitude
- * cell index into the high half of a Long and the 24-bit longitude cell index
- * into the low half (signed division is intentional so latitudes/longitudes
- * either side of 0 don't collide).
+ * The cell size is `0.01°` (E7: 100_000) — roughly 1.1 km at the equator and
+ * ~0.7 km at lat 50°. This sits one order of magnitude tighter than typical
+ * road-segment lengths and matches the spatial scale of OSM tile resolution
+ * around z14, giving the speed-limit lookup a much smaller candidate set per
+ * query than the original 0.08° (~9 km) grid.
  *
- * The same encoding is used by the SQL-backed `osm_way_cell` table, so any
- * change here MUST also be reflected in the migration.
+ * The key packs the latitude cell index into the high half of a Long
+ * (`shl 24`) and the longitude cell index into the low 24 bits with
+ * `and 0xFFFFFF`. Signed floor division is intentional so latitudes /
+ * longitudes either side of 0 don't collide. With a 0.01° cell:
+ *
+ *  - latitude cell range is roughly ±9_000 (well within 16 bits)
+ *  - longitude cell range is roughly ±18_000 (well within the 24-bit signed
+ *    slot ±8_388_607)
+ *
+ * The same encoding is used by the SQL-backed `osm_way_cell` table.
+ * Because the key space is purely a function of the constants above,
+ * **any change to [CELL_E7] invalidates every existing `osm_way_cell` row**
+ * — `MIGRATION_31_32` drops the table and a background reindexer rebuilds it
+ * from the preserved `osm_way` bboxes on first launch after upgrade.
  */
 object OsmGridIndex {
 
-	const val CELL_DEGREES = 0.08
-	const val CELL_E7 = 800_000
+	const val CELL_DEGREES = 0.01
+	const val CELL_E7 = 100_000
 
 	/** Returns the cell key for a single point in E7 coordinates. */
 	fun cellKey(latE7: Int, lonE7: Int): Long {

osm/src/test/java/com/adsamcik/tracker/osm/io/OsmGridIndexTest.kt

@@ -102,4 +102,97 @@ class OsmGridIndexTest {
 		).toList()
 		bbox.shouldContainExactlyInAnyOrder(neighbors)
 	}
+
+	// region cell-size invariants (locked in by the v31->v32 migration)
+
+	@Test
+	fun `cell size is 0_01 degrees so road-segment-scale lookups are selective`() {
+		OsmGridIndex.CELL_DEGREES shouldBe 0.01
+		OsmGridIndex.CELL_E7 shouldBe 100_000
+	}
+
+	@Test
+	fun `cell width at lat 50 is roughly 1_1 km wide and 0_7 km tall`() {
+		// One cell at lat 50: 0.01° latitude = ~1113 m great-circle.
+		// 0.01° longitude shrinks by cos(50°) ≈ 0.6428 → ~715 m.
+		val metresPerDegLat = 111_320.0
+		val expectedLatM = OsmGridIndex.CELL_DEGREES * metresPerDegLat
+		val expectedLonM = OsmGridIndex.CELL_DEGREES * metresPerDegLat * Math.cos(Math.toRadians(50.0))
+		(expectedLatM in 1108.0..1118.0) shouldBe true
+		(expectedLonM in 710.0..720.0) shouldBe true
+	}
+
+	@Test
+	fun `cellKeysForBbox covers a 5km x 5km bbox at lat 50 with at most ~50 cells`() {
+		// 5 km north-south ≈ 0.045° latitude → ~5 cells.
+		// 5 km east-west at lat 50 ≈ 0.070° longitude → ~7 cells.
+		// Total grid block: ~5x7 ≈ 35 cells (plus boundary overlap, capped at 8x10 = 80).
+		val centerLatE7 = 500_000_000 // lat 50.0°
+		val centerLonE7 = 144_000_000 // lon 14.4°
+		val halfLatE7 = 250_000        // 0.025° → 2.78 km
+		val halfLonE7 = 350_000        // 0.035° at lat 50 → ~2.5 km
+		val keys = OsmGridIndex.cellKeysForBbox(
+			minLatE7 = centerLatE7 - halfLatE7,
+			maxLatE7 = centerLatE7 + halfLatE7,
+			minLonE7 = centerLonE7 - halfLonE7,
+			maxLonE7 = centerLonE7 + halfLonE7,
+		)
+		// 5 lat × 7 lon = 35; allow ±1 on each axis for boundary alignment.
+		(keys.size in 30..56) shouldBe true
+		// Same bbox under the old 0.08° (E7 800_000) grid resolved to a single
+		// cell, so the new index is at minimum an order of magnitude more
+		// selective on this size of query.
+		(keys.size >= 30) shouldBe true
+	}
+
+	@Test
+	fun `equator boundary lat 0 returns adjacent cells north and south of it`() {
+		val north = OsmGridIndex.cellKey(latE7 = 50_000, lonE7 = 0)
+		val onLine = OsmGridIndex.cellKey(latE7 = 0, lonE7 = 0)
+		val south = OsmGridIndex.cellKey(latE7 = -50_000, lonE7 = 0)
+		// (lat=0 falls into the [0,CELL_E7) cell, same as north).
+		north shouldBe onLine
+		(south != onLine) shouldBe true
+	}
+
+	@Test
+	fun `prime meridian boundary lon 0 separates east and west cells`() {
+		val east = OsmGridIndex.cellKey(latE7 = 500_000_000, lonE7 = 50_000)
+		val west = OsmGridIndex.cellKey(latE7 = 500_000_000, lonE7 = -50_000)
+		(east != west) shouldBe true
+	}
+
+	@Test
+	fun `dateline lon 180 packs into the 24-bit signed slot without collision`() {
+		// lonE7 = +1_800_000_000 → cell index +18_000 fits the signed-24-bit
+		// slot range ±8_388_607 with huge headroom. Make sure
+		// +180° and -180° produce different keys (they're physically the same
+		// meridian but different inputs; OSM never stores +180.0 anyway).
+		val east = OsmGridIndex.cellKey(latE7 = 0, lonE7 = 1_800_000_000)
+		val west = OsmGridIndex.cellKey(latE7 = 0, lonE7 = -1_800_000_000)
+		// Both fit (no overflow / sign-flip), and they decode to distinct cells.
+		(east != west) shouldBe true
+	}
+
+	@Test
+	fun `north pole lat 90 packs without overflow into the high-bit slot`() {
+		val polar = OsmGridIndex.cellKey(latE7 = 900_000_000, lonE7 = 0)
+		val justBelow = OsmGridIndex.cellKey(latE7 = 899_900_000, lonE7 = 0)
+		(polar != justBelow) shouldBe true
+	}
+
+	@Test
+	fun `keys for two adjacent cells decode to consecutive lat or lon indices`() {
+		// Sanity check that the packing is recoverable; lat in high bits,
+		// lon in the low 24 bits as a signed value.
+		val key = OsmGridIndex.cellKey(latE7 = 500_000_000, lonE7 = 144_000_000)
+		val latCell = key shr 24
+		val lonCellRaw = (key and 0xFFFFFFL).toInt()
+		// 0xFFFFFF is unsigned; reconstruct sign manually for negatives.
+		val lonCell = if ((lonCellRaw and 0x800000) != 0) lonCellRaw or 0xFF000000.toInt() else lonCellRaw
+		latCell shouldBe 5_000L
+		lonCell shouldBe 1_440
+	}
+
+	// endregion
 }

sbase/src/main/java/com/adsamcik/tracker/shared/base/database/dao/OsmWayCellDao.kt

@@ -11,8 +11,10 @@ import com.adsamcik.tracker.shared.base.database.data.OsmWayCellEntity
  * [com.adsamcik.tracker.shared.base.database.data.OsmWayEntity] rows and
  * the grid cells their bounding boxes overlap.
  *
- * `cell_key` is computed by `(latE7 / 800_000) << 24 | (lonE7 / 800_000) & 0xFFFFFF`.
- * The 24-bit lon slot leaves us headroom for the full [-180°,+180°] range.
+ * `cell_key` is computed by `(latE7 / CELL_E7) << 24 | (lonE7 / CELL_E7) & 0xFFFFFF`,
+ * with `CELL_E7` defined in `com.adsamcik.tracker.osm.io.OsmGridIndex`. The
+ * 24-bit lon slot leaves headroom for the full [-180°,+180°] range at the
+ * current 0.01° cell size and any reasonable future tightening.
  */
 @Dao
 interface OsmWayCellDao {

sbase/src/main/java/com/adsamcik/tracker/shared/base/database/data/OsmWayCellEntity.kt

@@ -9,13 +9,16 @@ import androidx.room.Index
  * Spatial grid index linking an [OsmWayEntity] to every coarse grid cell its
  * bounding box overlaps.
  *
- * Phase 2a uses a simple square-degree grid keyed as
- * `(latE7 / 800_000) << 24 | (lonE7 / 800_000) & 0xFFFFFF` — i.e. cells of
- * roughly 0.08° (~9 km at the equator). Coarser than S2 level 14 but adequate
- * for snap-to-nearest-road queries with a tolerance under 100 m, and it avoids
- * pulling in an S2 dependency that the rest of the tracker doesn't already use.
+ * Cell keys are computed by [com.adsamcik.tracker.osm.io.OsmGridIndex] as
+ * `(latE7 / CELL_E7) << 24 | (lonE7 / CELL_E7) & 0xFFFFFF`. The current cell
+ * size is `0.01°` (E7: 100_000), roughly 1.1 km at the equator — tight enough
+ * that the snap-to-nearest-road query loads a small candidate set even in
+ * dense urban areas.
  *
- * One way can appear in many cells when its bbox straddles a grid line.
+ * One way can appear in many cells when its bbox straddles a grid line. The
+ * source of truth for the cell-key encoding is [com.adsamcik.tracker.osm.io.OsmGridIndex];
+ * any change to that constant invalidates every row in this table and must be
+ * paired with a Room migration that drops the contents plus a reindex pass.
  */
 @Entity(
 	tableName = "osm_way_cell",