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

package/android/src/main/java/com/brickssoft/locationtracking/data/SqlSupport.kt

@@ -0,0 +1,79 @@
+package com.brickssoft.locationtracking.data
+
+import android.database.sqlite.SQLiteDatabase
+import android.database.sqlite.SQLiteStatement
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.TrackingException
+import org.json.JSONException
+import kotlin.coroutines.cancellation.CancellationException
+
+/** Maximum bound parameters per statement (old SQLite builds allow 999). */
+internal const val MAX_SQL_PARAMS = 500
+
+/** `?,?,...,?` with [count] placeholders. */
+internal fun placeholders(count: Int): String = List(count) { "?" }.joinToString(",")
+
+/** Runs [body] in an immediate transaction; commits if it returns normally, rolls back if it throws. */
+internal inline fun <T> SQLiteDatabase.inTransaction(body: () -> T): T {
+    beginTransactionNonExclusive()
+    try {
+        val result = body()
+        setTransactionSuccessful()
+        return result
+    } finally {
+        endTransaction()
+    }
+}
+
+/** Deletes the rows whose [column] is one of [keys], in chunks of at most [MAX_SQL_PARAMS], in one transaction. */
+internal fun SQLiteDatabase.deleteIn(table: String, column: String, keys: Collection<String>): Int = inTransaction {
+    var deleted = 0
+    for (chunk in keys.distinct().chunked(MAX_SQL_PARAMS)) {
+        deleted += delete(table, "$column IN (${placeholders(chunk.size)})", chunk.toTypedArray())
+    }
+    deleted
+}
+
+/** A row whose JSON could not be decoded: its key and the exact text that was read. */
+internal class UndecodableRow(val key: String, val json: String)
+
+/**
+ * Deletes each of [rows] only if its [jsonColumn] still holds the text that failed to decode, so a valid row
+ * written concurrently under the same key survives. Returns the number of rows deleted.
+ */
+internal fun SQLiteDatabase.deleteUndecodable(
+    table: String,
+    keyColumn: String,
+    jsonColumn: String,
+    rows: List<UndecodableRow>,
+): Int = inTransaction {
+    rows.sumOf { delete(table, "$keyColumn = ? AND $jsonColumn = ?", arrayOf(it.key, it.json)) }
+}
+
+/** Compiles [sql], lets [bind] bind its arguments and runs it; returns the number of changed rows. */
+internal inline fun SQLiteDatabase.executeUpdateDelete(sql: String, bind: SQLiteStatement.() -> Unit): Int =
+    compileStatement(sql).use { statement ->
+        statement.bind()
+        statement.executeUpdateDelete()
+    }
+
+/** Runs [block] (JSON encoding); a `JSONException` (e.g. from NaN) becomes `TrackingException(INVALID_ARGUMENT)`. */
+internal inline fun <T> encoding(what: String, block: () -> T): T = try {
+    block()
+} catch (e: JSONException) {
+    throw TrackingException(ErrorCode.INVALID_ARGUMENT, "$what cannot be stored: ${e.message}", e)
+}
+
+/**
+ * Runs [block] and converts any failure except cancellation and [TrackingException] into
+ * `TrackingException(IO_ERROR)`, the only exception type that crosses component boundaries.
+ */
+internal inline fun <T> ioErrors(what: String, block: () -> T): T = try {
+    block()
+} catch (e: CancellationException) {
+    throw e
+} catch (e: TrackingException) {
+    throw e
+} catch (e: Exception) {
+    throw TrackingException(ErrorCode.IO_ERROR, "$what failed: ${e.message ?: e.javaClass.simpleName}", e)
+}

package/android/src/main/java/com/brickssoft/locationtracking/data/SqliteGeofenceStore.kt

@@ -0,0 +1,144 @@
+package com.brickssoft.locationtracking.data
+
+import android.content.ContentValues
+import android.database.DatabaseUtils
+import android.database.sqlite.SQLiteDatabase
+import com.brickssoft.locationtracking.core.AppDispatchers
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.GeofenceJson
+import com.brickssoft.locationtracking.model.GeofenceSpec
+import com.brickssoft.locationtracking.model.JsonUtil
+import kotlinx.coroutines.withContext
+import org.json.JSONObject
+
+/**
+ * SQLite geofence registry (table `geofences` of [TrackingDatabase]). All work runs on [AppDispatchers.io];
+ * failures are thrown as `TrackingException(IO_ERROR)`.
+ *
+ * - Specs are stored as `GeofenceJson`; [all] is ordered by identifier.
+ * - [upsert] replaces the spec but keeps an existing runtime; [remove] and [removeAll] delete the runtime too.
+ * - [setRuntime] stores `{insideCircle, insidePolygon, enteredAt}` and is ignored for an unknown identifier.
+ * - A row whose spec cannot be decoded is logged, skipped and deleted.
+ *
+ * Thread-safe: SQLiteDatabase serializes writes and [upsert] runs in one transaction. Reads run concurrently with
+ * writes (WAL).
+ */
+class SqliteGeofenceStore(
+    private val database: TrackingDatabase,
+    private val dispatchers: AppDispatchers,
+) : GeofenceStore {
+    override suspend fun upsert(geofences: List<GeofenceSpec>) {
+        if (geofences.isEmpty()) return
+        io("upsert") { db ->
+            val rows = geofences.map { g ->
+                g.identifier to encoding("geofence '${g.identifier}'") { GeofenceJson.toJson(g).toString() }
+            }
+            db.inTransaction {
+                for ((id, json) in rows) {
+                    // Update first so an existing runtime_json is kept (no UPSERT syntax before SQLite 3.24 / API 30).
+                    val values = ContentValues(2).apply { put(GeofencesTable.JSON, json) }
+                    val updated = db.update(GeofencesTable.NAME, values, "${GeofencesTable.ID} = ?", arrayOf(id))
+                    if (updated == 0) {
+                        values.put(GeofencesTable.ID, id)
+                        db.insertOrThrow(GeofencesTable.NAME, null, values)
+                    }
+                }
+            }
+        }
+    }
+
+    override suspend fun remove(ids: Collection<String>): Int {
+        if (ids.isEmpty()) return 0
+        return io("remove") { db -> db.deleteIn(GeofencesTable.NAME, GeofencesTable.ID, ids) }
+    }
+
+    override suspend fun removeAll(): Int = io("removeAll") { db ->
+        // "1" (not null) makes SQLite report the number of deleted rows.
+        db.delete(GeofencesTable.NAME, "1", null)
+    }
+
+    override suspend fun all(): List<GeofenceSpec> = io("all") { db -> query(db, null) }
+
+    override suspend fun get(id: String): GeofenceSpec? = io("get") { db -> query(db, id).firstOrNull() }
+
+    override suspend fun count(): Int = io("count") { db ->
+        DatabaseUtils.queryNumEntries(db, GeofencesTable.NAME).toInt()
+    }
+
+    override suspend fun setRuntime(id: String, runtime: GeofenceRuntime) {
+        io("setRuntime") { db ->
+            val values = ContentValues(1).apply {
+                put(GeofencesTable.RUNTIME_JSON, GeofenceRuntimeJson.toJson(runtime).toString())
+            }
+            val updated = db.update(GeofencesTable.NAME, values, "${GeofencesTable.ID} = ?", arrayOf(id))
+            if (updated == 0) Logger.d(TAG, "ignoring runtime of unknown geofence '$id'")
+        }
+    }
+
+    override suspend fun runtimes(): Map<String, GeofenceRuntime> = io("runtimes") { db ->
+        val result = LinkedHashMap<String, GeofenceRuntime>()
+        db.rawQuery(
+            "SELECT ${GeofencesTable.ID}, ${GeofencesTable.RUNTIME_JSON} FROM ${GeofencesTable.NAME} " +
+                "WHERE ${GeofencesTable.RUNTIME_JSON} IS NOT NULL ORDER BY ${GeofencesTable.ID}",
+            null,
+        ).use { cursor ->
+            while (cursor.moveToNext()) {
+                val id = cursor.getString(0)
+                val runtime = JsonUtil.parseObject(cursor.getString(1))?.let { GeofenceRuntimeJson.fromJson(it) }
+                if (runtime != null) result[id] = runtime else Logger.w(TAG, "skipping undecodable runtime of '$id'")
+            }
+        }
+        result
+    }
+
+    private suspend fun <T> io(what: String, block: (SQLiteDatabase) -> T): T = withContext(dispatchers.io) {
+        ioErrors("geofence store $what") { block(database.writableDatabase) }
+    }
+
+    /** Specs ordered by identifier ([id] = null: all). Undecodable rows are logged, skipped and deleted. */
+    private fun query(db: SQLiteDatabase, id: String?): List<GeofenceSpec> {
+        val result = ArrayList<GeofenceSpec>()
+        val undecodable = ArrayList<UndecodableRow>()
+        val where = if (id != null) " WHERE ${GeofencesTable.ID} = ?" else ""
+        db.rawQuery(
+            "SELECT ${GeofencesTable.ID}, ${GeofencesTable.JSON} FROM ${GeofencesTable.NAME}$where " +
+                "ORDER BY ${GeofencesTable.ID}",
+            id?.let { arrayOf(it) },
+        ).use { cursor ->
+            while (cursor.moveToNext()) {
+                val rowId = cursor.getString(0)
+                val json = cursor.getString(1)
+                try {
+                    result += GeofenceJson.fromJson(JSONObject(json))
+                } catch (e: Exception) {
+                    Logger.e(TAG, "skipping undecodable geofence '$rowId'", e)
+                    undecodable += UndecodableRow(rowId, json)
+                }
+            }
+        }
+        if (undecodable.isNotEmpty()) {
+            val removed = db.deleteUndecodable(GeofencesTable.NAME, GeofencesTable.ID, GeofencesTable.JSON, undecodable)
+            Logger.w(TAG, "deleted $removed undecodable geofence(s)")
+        }
+        return result
+    }
+
+    private companion object {
+        const val TAG = "LT.GeofenceStore"
+    }
+}
+
+/** `runtime_json` codec: `{"insideCircle":bool,"insidePolygon":bool,"enteredAt":ms|null}`. */
+internal object GeofenceRuntimeJson {
+    fun toJson(runtime: GeofenceRuntime): JSONObject = JSONObject()
+        .put("insideCircle", runtime.insideCircle)
+        .put("insidePolygon", runtime.insidePolygon)
+        .put("enteredAt", JsonUtil.orNull(runtime.enteredAt))
+
+    /** Lenient: missing flags are false, a missing `enteredAt` is null. */
+    fun fromJson(json: JSONObject): GeofenceRuntime = GeofenceRuntime(
+        insideCircle = JsonUtil.optBoolean(json, "insideCircle") ?: false,
+        insidePolygon = JsonUtil.optBoolean(json, "insidePolygon") ?: false,
+        enteredAt = JsonUtil.optLong(json, "enteredAt"),
+    )
+}

package/android/src/main/java/com/brickssoft/locationtracking/data/SqliteLocationStore.kt

@@ -0,0 +1,215 @@
+package com.brickssoft.locationtracking.data
+
+import android.content.ContentValues
+import android.database.DatabaseUtils
+import android.database.sqlite.SQLiteDatabase
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.AppDispatchers
+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.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+import com.brickssoft.locationtracking.model.RecordJson
+import kotlinx.coroutines.withContext
+import org.json.JSONObject
+
+/**
+ * SQLite record queue (table `records` of [TrackingDatabase]). All work runs on [AppDispatchers.io]; failures are
+ * thrown as `TrackingException(IO_ERROR)`.
+ *
+ * - Rows hold `RecordJson.toJson(record)` without `sent_at`. Inserting an existing uuid replaces the row (and
+ *   resets its attempt counters).
+ * - [list] is oldest first (`recorded_at`, then insertion order). A row that cannot be decoded is logged, skipped
+ *   and deleted (a limited page is refilled with the next rows), so a bad row cannot block the queue. [count] still
+ *   includes such a row until a [list] has seen it.
+ * - Pruning runs on first use and after every [PRUNE_EVERY] inserts, for **every** event type: heartbeat and
+ *   audit records are dropped like location records. First, records whose `recorded_at` is older than
+ *   `persistence.maxDaysToPersist` days are deleted (skipped if that is <= 0); then, if
+ *   `persistence.maxRecordsToPersist > 0`, only the newest N records (by `recorded_at`, then insertion order)
+ *   are kept. Between prunes the queue may exceed `maxRecordsToPersist` by fewer than [PRUNE_EVERY] records.
+ *   Pruning failures are logged, never thrown.
+ *
+ * Thread-safe: SQLiteDatabase serializes writes and multi-statement writes run in transactions; a lock guards the
+ * insert counter and pruning. Reads run concurrently with writes (WAL).
+ */
+class SqliteLocationStore(
+    private val database: TrackingDatabase,
+    private val configStore: ConfigStore,
+    private val clock: Clock,
+    private val dispatchers: AppDispatchers,
+) : LocationStore {
+    private val pruneLock = Any()
+
+    @Volatile
+    private var initialPruneDone = false
+
+    /** Guarded by [pruneLock]. */
+    private var insertsSincePrune = 0
+
+    override suspend fun insert(record: Record) = io("insert") { db ->
+        val values = ContentValues(4).apply {
+            put(RecordsTable.UUID, record.uuid)
+            put(RecordsTable.EVENT, record.event.wire)
+            put(RecordsTable.RECORDED_AT, record.recordedAt)
+            put(RecordsTable.JSON, encoding("record ${record.uuid}") { RecordJson.toJson(record).toString() })
+        }
+        synchronized(pruneLock) {
+            val rowId = db.insertWithOnConflict(RecordsTable.NAME, null, values, SQLiteDatabase.CONFLICT_REPLACE)
+            if (rowId == -1L) throw TrackingException(ErrorCode.IO_ERROR, "record ${record.uuid} was not inserted")
+            insertsSincePrune++
+            if (insertsSincePrune >= PRUNE_EVERY) prune(db)
+        }
+    }
+
+    override suspend fun list(limit: Int, events: Set<RecordEvent>?): List<Record> {
+        if (limit == 0 || events?.isEmpty() == true) return emptyList()
+        return io("list") { db ->
+            var page = queryPage(db, limit, events)
+            var passes = 0
+            while (page.undecodable.isNotEmpty() && passes++ < MAX_REPAIR_PASSES) {
+                val removed =
+                    db.deleteUndecodable(RecordsTable.NAME, RecordsTable.UUID, RecordsTable.JSON, page.undecodable)
+                Logger.w(TAG, "deleted $removed undecodable record(s)")
+                // Without a limit every row was read already; with one, re-query to refill the page.
+                if (limit < 0) break
+                page = queryPage(db, limit, events)
+            }
+            page.records
+        }
+    }
+
+    override suspend fun count(events: Set<RecordEvent>?): Int {
+        if (events?.isEmpty() == true) return 0
+        return io("count") { db ->
+            if (events == null) {
+                DatabaseUtils.queryNumEntries(db, RecordsTable.NAME).toInt()
+            } else {
+                DatabaseUtils.queryNumEntries(db, RecordsTable.NAME, eventFilter(events), eventArgs(events)).toInt()
+            }
+        }
+    }
+
+    override suspend fun delete(uuids: Collection<String>): Int {
+        if (uuids.isEmpty()) return 0
+        return io("delete") { db -> db.deleteIn(RecordsTable.NAME, RecordsTable.UUID, uuids) }
+    }
+
+    override suspend fun deleteAll(): Int = io("deleteAll") { db ->
+        // "1" (not null) makes SQLite report the number of deleted rows.
+        db.delete(RecordsTable.NAME, "1", null)
+    }
+
+    override suspend fun markAttempt(uuids: Collection<String>, at: Long) {
+        if (uuids.isEmpty()) return
+        io("markAttempt") { db ->
+            db.inTransaction {
+                // One parameter is `at`, so each chunk leaves room for it.
+                for (chunk in uuids.distinct().chunked(MAX_SQL_PARAMS - 1)) {
+                    db.executeUpdateDelete(
+                        "UPDATE ${RecordsTable.NAME} " +
+                            "SET ${RecordsTable.ATTEMPTS} = ${RecordsTable.ATTEMPTS} + 1, " +
+                            "${RecordsTable.LAST_ATTEMPT_AT} = ? " +
+                            "WHERE ${RecordsTable.UUID} IN (${placeholders(chunk.size)})",
+                    ) {
+                        bindLong(1, at)
+                        chunk.forEachIndexed { i, uuid -> bindString(i + 2, uuid) }
+                    }
+                }
+            }
+        }
+    }
+
+    /** Opens the database on [AppDispatchers.io], prunes once per instance, then runs [block]. */
+    private suspend fun <T> io(what: String, block: (SQLiteDatabase) -> T): T = withContext(dispatchers.io) {
+        ioErrors("location store $what") {
+            val db = database.writableDatabase
+            pruneOnFirstUse(db)
+            block(db)
+        }
+    }
+
+    private fun pruneOnFirstUse(db: SQLiteDatabase) {
+        if (initialPruneDone) return
+        synchronized(pruneLock) {
+            if (!initialPruneDone) {
+                prune(db)
+                initialPruneDone = true
+            }
+        }
+    }
+
+    /** Deletes expired and surplus records (see class docs). Caller holds [pruneLock]. Never throws. */
+    private fun prune(db: SQLiteDatabase) {
+        insertsSincePrune = 0
+        val persistence = configStore.config.value.persistence
+        try {
+            var expired = 0
+            var surplus = 0
+            db.inTransaction {
+                if (persistence.maxDaysToPersist > 0) {
+                    val cutoff = clock.now() - persistence.maxDaysToPersist * DAY_MS
+                    expired = db.executeUpdateDelete(
+                        "DELETE FROM ${RecordsTable.NAME} WHERE ${RecordsTable.RECORDED_AT} < ?",
+                    ) { bindLong(1, cutoff) }
+                }
+                if (persistence.maxRecordsToPersist > 0) {
+                    surplus = db.executeUpdateDelete(
+                        "DELETE FROM ${RecordsTable.NAME} WHERE rowid IN (SELECT rowid FROM ${RecordsTable.NAME} " +
+                            "ORDER BY ${RecordsTable.RECORDED_AT} DESC, rowid DESC LIMIT -1 OFFSET ?)",
+                    ) { bindLong(1, persistence.maxRecordsToPersist.toLong()) }
+                }
+            }
+            if (expired + surplus > 0) {
+                Logger.i(
+                    TAG,
+                    "pruned $expired record(s) older than ${persistence.maxDaysToPersist} day(s) and " +
+                        "$surplus over the limit of ${persistence.maxRecordsToPersist}",
+                )
+            }
+        } catch (e: Exception) {
+            Logger.e(TAG, "pruning failed", e)
+        }
+    }
+
+    private class Page(val records: List<Record>, val undecodable: List<UndecodableRow>)
+
+    private fun queryPage(db: SQLiteDatabase, limit: Int, events: Set<RecordEvent>?): Page {
+        val sql = StringBuilder("SELECT ${RecordsTable.UUID}, ${RecordsTable.JSON} FROM ${RecordsTable.NAME}")
+        if (events != null) sql.append(" WHERE ").append(eventFilter(events))
+        sql.append(" ORDER BY ${RecordsTable.RECORDED_AT} ASC, rowid ASC")
+        if (limit > 0) sql.append(" LIMIT ").append(limit)
+        val records = ArrayList<Record>()
+        val undecodable = ArrayList<UndecodableRow>()
+        db.rawQuery(sql.toString(), events?.let { eventArgs(it) }).use { cursor ->
+            while (cursor.moveToNext()) {
+                val uuid = cursor.getString(0)
+                val json = cursor.getString(1)
+                try {
+                    records += RecordJson.fromJson(JSONObject(json))
+                } catch (e: Exception) {
+                    Logger.e(TAG, "skipping undecodable record $uuid", e)
+                    undecodable += UndecodableRow(uuid, json)
+                }
+            }
+        }
+        return Page(records, undecodable)
+    }
+
+    private fun eventFilter(events: Set<RecordEvent>): String =
+        "${RecordsTable.EVENT} IN (${placeholders(events.size)})"
+
+    private fun eventArgs(events: Set<RecordEvent>): Array<String> = events.map { it.wire }.toTypedArray()
+
+    companion object {
+        /** Pruning runs after this many inserts (and on first use). */
+        const val PRUNE_EVERY = 50
+
+        /** Bounds the refill loop of [list] when many undecodable rows are found. */
+        private const val MAX_REPAIR_PASSES = 10
+
+        private const val DAY_MS = 86_400_000L
+        private const val TAG = "LT.LocationStore"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/data/Stores.kt

@@ -0,0 +1,45 @@
+package com.brickssoft.locationtracking.data
+
+import com.brickssoft.locationtracking.model.GeofenceSpec
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+
+/**
+ * The record queue. Pruning (`maxDaysToPersist` / `maxRecordsToPersist`) is internal: on open and every 50 inserts.
+ */
+interface LocationStore {
+    suspend fun insert(record: Record)
+
+    /** Oldest first; `limit < 0` = all; `events == null` = every event. */
+    suspend fun list(limit: Int = -1, events: Set<RecordEvent>? = null): List<Record>
+
+    suspend fun count(events: Set<RecordEvent>? = null): Int
+
+    suspend fun delete(uuids: Collection<String>): Int
+
+    suspend fun deleteAll(): Int
+
+    /** Increments `attempts` and sets `last_attempt_at`. */
+    suspend fun markAttempt(uuids: Collection<String>, at: Long)
+}
+
+/** Per-geofence runtime used for polygon hit-testing and dwell synthesis. */
+data class GeofenceRuntime(val insideCircle: Boolean, val insidePolygon: Boolean, val enteredAt: Long?)
+
+interface GeofenceStore {
+    suspend fun upsert(geofences: List<GeofenceSpec>)
+
+    suspend fun remove(ids: Collection<String>): Int
+
+    suspend fun removeAll(): Int
+
+    suspend fun all(): List<GeofenceSpec>
+
+    suspend fun get(id: String): GeofenceSpec?
+
+    suspend fun count(): Int
+
+    suspend fun setRuntime(id: String, runtime: GeofenceRuntime)
+
+    suspend fun runtimes(): Map<String, GeofenceRuntime>
+}

package/android/src/main/java/com/brickssoft/locationtracking/data/TrackingDatabase.kt

@@ -0,0 +1,111 @@
+package com.brickssoft.locationtracking.data
+
+import android.content.Context
+import android.database.sqlite.SQLiteDatabase
+import android.database.sqlite.SQLiteOpenHelper
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+
+/**
+ * SQLiteOpenHelper for [Constants.DATABASE_NAME] (schema [VERSION]), shared by [SqliteLocationStore] and
+ * [SqliteGeofenceStore]. Write-ahead logging is enabled, so readers never block the single writer.
+ *
+ * Schema v1:
+ * - `records`: the upload queue. `json` is `RecordJson.toJson(record)` without `sent_at`; `event` and `recorded_at`
+ *   duplicate the JSON for filtering, ordering and pruning; `attempts` / `last_attempt_at` track failed uploads.
+ *   Indexed on `recorded_at` and on `(event, recorded_at)`.
+ * - `geofences`: `json` is `GeofenceJson.toJson(spec)`; `runtime_json` is `{insideCircle, insidePolygon, enteredAt}`
+ *   or null.
+ *
+ * @param name database file name; `null` creates an in-memory database.
+ */
+class TrackingDatabase(
+    context: Context,
+    name: String? = Constants.DATABASE_NAME,
+) : SQLiteOpenHelper(context.applicationContext ?: context, name, null, VERSION) {
+
+    init {
+        // Must be set before the database is first opened.
+        setWriteAheadLoggingEnabled(true)
+    }
+
+    override fun onCreate(db: SQLiteDatabase) {
+        db.execSQL(
+            "CREATE TABLE ${RecordsTable.NAME} (" +
+                "${RecordsTable.UUID} TEXT PRIMARY KEY NOT NULL, " +
+                "${RecordsTable.EVENT} TEXT NOT NULL, " +
+                "${RecordsTable.RECORDED_AT} INTEGER NOT NULL, " +
+                "${RecordsTable.JSON} TEXT NOT NULL, " +
+                "${RecordsTable.ATTEMPTS} INTEGER NOT NULL DEFAULT 0, " +
+                "${RecordsTable.LAST_ATTEMPT_AT} INTEGER)",
+        )
+        db.execSQL(
+            "CREATE INDEX ${RecordsTable.INDEX_RECORDED_AT} ON ${RecordsTable.NAME}(${RecordsTable.RECORDED_AT})",
+        )
+        db.execSQL(
+            "CREATE INDEX ${RecordsTable.INDEX_EVENT_RECORDED_AT} " +
+                "ON ${RecordsTable.NAME}(${RecordsTable.EVENT}, ${RecordsTable.RECORDED_AT})",
+        )
+        db.execSQL(
+            "CREATE TABLE ${GeofencesTable.NAME} (" +
+                "${GeofencesTable.ID} TEXT PRIMARY KEY NOT NULL, " +
+                "${GeofencesTable.JSON} TEXT NOT NULL, " +
+                "${GeofencesTable.RUNTIME_JSON} TEXT)",
+        )
+        Logger.i(TAG, "created database schema v$VERSION")
+    }
+
+    /**
+     * Migration strategy (only v1 exists today). `SQLiteOpenHelper` runs this inside a transaction.
+     *
+     * Every schema change bumps [VERSION] and adds one step here, applied in order:
+     * `for (v in oldVersion + 1..newVersion) when (v) { 2 -> migrateTo2(db) ... }`.
+     * - `records` must never be dropped or recreated: it holds queued heartbeat and audit records that have not
+     *   been uploaded yet. Steps are additive (`ALTER TABLE ... ADD COLUMN` with a default, `CREATE INDEX IF NOT
+     *   EXISTS`), or, for incompatible changes, create `records_new`, `INSERT INTO records_new SELECT ... FROM
+     *   records`, drop the old table and rename the new one, all in this transaction.
+     * - The `json` column is self-describing, so new columns can be backfilled from it in the same step.
+     * - `geofences` follows the same rule (the app registered those regions and expects them back).
+     * - Steps must be idempotent (check `PRAGMA table_info` before `ADD COLUMN`, use `IF NOT EXISTS`), because
+     *   [onDowngrade] keeps a newer schema and a later upgrade runs the same steps again.
+     */
+    override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) {
+        Logger.i(TAG, "database upgrade v$oldVersion -> v$newVersion: no migration steps defined")
+    }
+
+    /**
+     * Keeps the newer schema and its data (the default would make every open fail, losing the queue). Because
+     * migrations are additive, this version's statements still work on it.
+     */
+    override fun onDowngrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) {
+        Logger.w(TAG, "database downgrade v$oldVersion -> v$newVersion: keeping the newer schema and its data")
+    }
+
+    companion object {
+        /** Current schema version. */
+        const val VERSION = 1
+
+        private const val TAG = "LT.Database"
+    }
+}
+
+/** Column names of the `records` table. */
+internal object RecordsTable {
+    const val NAME = "records"
+    const val UUID = "uuid"
+    const val EVENT = "event"
+    const val RECORDED_AT = "recorded_at"
+    const val JSON = "json"
+    const val ATTEMPTS = "attempts"
+    const val LAST_ATTEMPT_AT = "last_attempt_at"
+    const val INDEX_RECORDED_AT = "records_recorded_at"
+    const val INDEX_EVENT_RECORDED_AT = "records_event_recorded_at"
+}
+
+/** Column names of the `geofences` table. */
+internal object GeofencesTable {
+    const val NAME = "geofences"
+    const val ID = "id"
+    const val JSON = "json"
+    const val RUNTIME_JSON = "runtime_json"
+}