react-native-step-tracker-pro 1.0.0

package/android/src/main/java/com/steptrackerpro/core/StepStateStore.kt

@@ -0,0 +1,137 @@
+package com.steptrackerpro.core
+
+import android.content.Context
+import android.content.SharedPreferences
+
+/**
+ * Durable counter state. Kept in SharedPreferences rather than Room because it
+ * is written on nearly every sensor batch and must be readable synchronously
+ * from `onStartCommand` before any coroutine has a chance to run.
+ *
+ * Inspect on a debug build with:
+ *   adb shell run-as <applicationId> cat shared_prefs/StepTrackerProState.xml
+ */
+class StepStateStore(context: Context) {
+
+    private val prefs: SharedPreferences = context.applicationContext
+        .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+    /**
+     * Approximate boot timestamp. A change larger than [BOOT_DRIFT_TOLERANCE_MS]
+     * means the device rebooted and TYPE_STEP_COUNTER restarted from zero.
+     */
+    var bootId: Long
+        get() = prefs.getLong(KEY_BOOT_ID, 0L)
+        set(value) = prefs.edit().putLong(KEY_BOOT_ID, value).apply()
+
+    /** Raw sensor reading that corresponds to [anchorSteps]. */
+    var anchorValue: Float
+        get() = prefs.getFloat(KEY_ANCHOR_VALUE, -1f)
+        set(value) = prefs.edit().putFloat(KEY_ANCHOR_VALUE, value).apply()
+
+    /** Steps already attributed to [activeDate] at the anchor point. */
+    var anchorSteps: Int
+        get() = prefs.getInt(KEY_ANCHOR_STEPS, 0)
+        set(value) = prefs.edit().putInt(KEY_ANCHOR_STEPS, value).apply()
+
+    var lastRawValue: Float
+        get() = prefs.getFloat(KEY_LAST_RAW, -1f)
+        set(value) = prefs.edit().putFloat(KEY_LAST_RAW, value).apply()
+
+    /**
+     * `SystemClock.elapsedRealtime()` at the last sample. Unlike the wall clock
+     * it cannot be set by the user and it restarts at zero on every boot, so a
+     * value below the stored one is *proof* of a reboot rather than the hint
+     * [bootId] gives.
+     */
+    var lastElapsedRealtime: Long
+        get() = prefs.getLong(KEY_LAST_ELAPSED, 0L)
+        set(value) = prefs.edit().putLong(KEY_LAST_ELAPSED, value).apply()
+
+    var activeDate: String
+        get() = prefs.getString(KEY_ACTIVE_DATE, null) ?: DateKeys.today()
+        set(value) = prefs.edit().putString(KEY_ACTIVE_DATE, value).apply()
+
+    /** Cached total so `getTodaySteps()` is instant even with the service dead. */
+    var stepsToday: Int
+        get() = prefs.getInt(KEY_STEPS_TODAY, 0)
+        set(value) = prefs.edit().putInt(KEY_STEPS_TODAY, value).apply()
+
+    var trackingState: TrackingState
+        get() = TrackingState.from(prefs.getString(KEY_STATE, null))
+        set(value) = prefs.edit().putString(KEY_STATE, value.jsValue).apply()
+
+    var source: SensorSource
+        get() = SensorSource.from(prefs.getString(KEY_SOURCE, null))
+        set(value) = prefs.edit().putString(KEY_SOURCE, value.jsValue).apply()
+
+    var lastEventAt: Long
+        get() = prefs.getLong(KEY_LAST_EVENT_AT, 0L)
+        set(value) = prefs.edit().putLong(KEY_LAST_EVENT_AT, value).apply()
+
+    /** True when the user (or the OS) asked us to come back after reboot. */
+    var shouldAutoStart: Boolean
+        get() = prefs.getBoolean(KEY_AUTO_START, false)
+        set(value) = prefs.edit().putBoolean(KEY_AUTO_START, value).apply()
+
+    var lastHealthSyncAt: Long
+        get() = prefs.getLong(KEY_LAST_HC_SYNC, 0L)
+        set(value) = prefs.edit().putLong(KEY_LAST_HC_SYNC, value).apply()
+
+    /**
+     * Version stamp for Health Connect's `clientRecordVersion`, which resolves
+     * same-id collisions by keeping the higher value. It must never go
+     * backwards, so it cannot simply be the wall clock: after the user moves
+     * the clock back, every write would be silently discarded by the provider.
+     * Seeded from the clock so records written by earlier versions of this
+     * package are still superseded.
+     */
+    @Synchronized
+    fun nextHealthRecordVersion(): Long {
+        val next = maxOf(prefs.getLong(KEY_HC_VERSION, 0L) + 1L, System.currentTimeMillis())
+        prefs.edit().putLong(KEY_HC_VERSION, next).apply()
+        return next
+    }
+
+    /** One atomic write for the hot path, instead of six separate commits. */
+    fun writeCounterState(
+        bootId: Long,
+        anchorValue: Float,
+        anchorSteps: Int,
+        lastRaw: Float,
+        activeDate: String,
+        stepsToday: Int,
+        lastEventAt: Long,
+        lastElapsed: Long
+    ) {
+        prefs.edit()
+            .putLong(KEY_BOOT_ID, bootId)
+            .putFloat(KEY_ANCHOR_VALUE, anchorValue)
+            .putInt(KEY_ANCHOR_STEPS, anchorSteps)
+            .putFloat(KEY_LAST_RAW, lastRaw)
+            .putString(KEY_ACTIVE_DATE, activeDate)
+            .putInt(KEY_STEPS_TODAY, stepsToday)
+            .putLong(KEY_LAST_EVENT_AT, lastEventAt)
+            .putLong(KEY_LAST_ELAPSED, lastElapsed)
+            .apply()
+    }
+
+    companion object {
+        const val PREFS_NAME = "StepTrackerProState"
+        const val BOOT_DRIFT_TOLERANCE_MS = 60_000L
+
+        private const val KEY_BOOT_ID = "boot_id"
+        private const val KEY_ANCHOR_VALUE = "anchor_value"
+        private const val KEY_ANCHOR_STEPS = "anchor_steps"
+        private const val KEY_LAST_RAW = "last_raw_value"
+        private const val KEY_LAST_ELAPSED = "last_elapsed_realtime"
+        private const val KEY_ACTIVE_DATE = "active_date"
+        private const val KEY_STEPS_TODAY = "steps_today"
+        private const val KEY_STATE = "tracking_state"
+        private const val KEY_SOURCE = "sensor_source"
+        private const val KEY_LAST_EVENT_AT = "last_event_at"
+        private const val KEY_AUTO_START = "should_auto_start"
+        private const val KEY_LAST_HC_SYNC = "last_hc_sync_at"
+        private const val KEY_HC_VERSION = "hc_record_version"
+    }
+}

package/android/src/main/java/com/steptrackerpro/core/StepTrackerConfig.kt

@@ -0,0 +1,184 @@
+package com.steptrackerpro.core
+
+import android.content.Context
+import org.json.JSONObject
+
+/**
+ * Immutable snapshot of user config. Persisted as JSON so the foreground
+ * service can rebuild it after a process restart without touching JS.
+ */
+data class StepTrackerConfig(
+    val heightCm: Double = 170.0,
+    val weightKg: Double = 70.0,
+    /**
+     * Explicit override in metres. Zero means "derive from height and sex" -
+     * a non-zero default here made [MetricsCalculator.effectiveStride]'s
+     * documented fallback unreachable, so height never affected distance.
+     */
+    val strideLengthM: Double = 0.0,
+    val sex: String = "unspecified",
+    val dailyGoal: Int = 10_000,
+    val weeklyGoal: Int = 70_000,
+    val monthlyGoal: Int = 300_000,
+    val calorieCoefficient: Double = 0.57,
+    val historyRetentionDays: Int = 35,
+    val notificationTitle: String? = null,
+    val notificationText: String? = null,
+    val notificationIcon: String? = null,
+    val notificationChannelName: String? = null,
+    val notificationActions: Boolean = true,
+    val notificationThrottleMs: Long = 1_000L,
+    val eventThrottleMs: Long = 500L,
+    val persistEveryNSteps: Int = 10,
+    val healthConnectEnabled: Boolean = true,
+    val healthConnectSyncIntervalMinutes: Int = 30,
+    val remoteSyncUrl: String? = null,
+    val remoteSyncHeaders: Map<String, String> = emptyMap(),
+    val autoStartOnBoot: Boolean = true
+) {
+
+    /**
+     * Clamps every numeric field into a range the rest of the package can rely
+     * on. The TypeScript layer validates a few of these, but it is not the only
+     * way in: config is also rebuilt from persisted JSON after a process
+     * restart, and the native module can be called directly. A negative
+     * `calorieCoefficient` would report negative calories, a zero
+     * `persistEveryNSteps` a database write per step, and a negative throttle
+     * an event to JS per step.
+     */
+    fun sanitised(): StepTrackerConfig = copy(
+        heightCm = heightCm.coerceIn(50.0, 260.0),
+        weightKg = weightKg.coerceIn(10.0, 400.0),
+        // Zero is meaningful: it means "derive from height and sex".
+        strideLengthM = if (strideLengthM.isFinite()) strideLengthM.coerceIn(0.0, 3.0) else 0.0,
+        dailyGoal = dailyGoal.coerceAtLeast(0),
+        weeklyGoal = weeklyGoal.coerceAtLeast(0),
+        monthlyGoal = monthlyGoal.coerceAtLeast(0),
+        calorieCoefficient = if (calorieCoefficient.isFinite()) {
+            calorieCoefficient.coerceIn(0.0, 10.0)
+        } else {
+            StepTrackerConfig().calorieCoefficient
+        },
+        historyRetentionDays = historyRetentionDays.coerceAtLeast(1),
+        notificationThrottleMs = notificationThrottleMs.coerceAtLeast(0L),
+        eventThrottleMs = eventThrottleMs.coerceAtLeast(0L),
+        persistEveryNSteps = persistEveryNSteps.coerceAtLeast(1),
+        healthConnectSyncIntervalMinutes = healthConnectSyncIntervalMinutes.coerceAtLeast(0)
+    )
+
+    fun toJson(): JSONObject = JSONObject().apply {
+        put("height", heightCm)
+        put("weight", weightKg)
+        put("strideLength", strideLengthM)
+        put("sex", sex)
+        put("dailyGoal", dailyGoal)
+        put("weeklyGoal", weeklyGoal)
+        put("monthlyGoal", monthlyGoal)
+        put("calorieCoefficient", calorieCoefficient)
+        put("historyRetentionDays", historyRetentionDays)
+        put("notificationTitle", notificationTitle ?: JSONObject.NULL)
+        put("notificationText", notificationText ?: JSONObject.NULL)
+        put("notificationIcon", notificationIcon ?: JSONObject.NULL)
+        put("notificationChannelName", notificationChannelName ?: JSONObject.NULL)
+        put("notificationActions", notificationActions)
+        put("notificationThrottleMs", notificationThrottleMs)
+        put("eventThrottleMs", eventThrottleMs)
+        put("persistEveryNSteps", persistEveryNSteps)
+        put("healthConnectEnabled", healthConnectEnabled)
+        put("healthConnectSyncIntervalMinutes", healthConnectSyncIntervalMinutes)
+        put("remoteSyncUrl", remoteSyncUrl ?: JSONObject.NULL)
+        put("remoteSyncHeaders", JSONObject(remoteSyncHeaders as Map<*, *>))
+        put("autoStartOnBoot", autoStartOnBoot)
+    }
+
+    companion object {
+        fun fromJson(json: JSONObject): StepTrackerConfig {
+            val fallback = StepTrackerConfig()
+            val headers = HashMap<String, String>()
+            json.optJSONObject("remoteSyncHeaders")?.let { obj ->
+                obj.keys().forEach { key -> headers[key] = obj.optString(key) }
+            }
+            return StepTrackerConfig(
+                heightCm = json.optDouble("height", fallback.heightCm),
+                weightKg = json.optDouble("weight", fallback.weightKg),
+                strideLengthM = json.optDouble("strideLength", fallback.strideLengthM),
+                sex = json.optString("sex", fallback.sex),
+                dailyGoal = json.optInt("dailyGoal", fallback.dailyGoal),
+                weeklyGoal = json.optInt("weeklyGoal", fallback.weeklyGoal),
+                monthlyGoal = json.optInt("monthlyGoal", fallback.monthlyGoal),
+                calorieCoefficient = json.optDouble(
+                    "calorieCoefficient", fallback.calorieCoefficient
+                ),
+                historyRetentionDays = json.optInt(
+                    "historyRetentionDays", fallback.historyRetentionDays
+                ),
+                notificationTitle = json.optStringOrNull("notificationTitle"),
+                notificationText = json.optStringOrNull("notificationText"),
+                notificationIcon = json.optStringOrNull("notificationIcon"),
+                notificationChannelName = json.optStringOrNull("notificationChannelName"),
+                notificationActions = json.optBoolean(
+                    "notificationActions", fallback.notificationActions
+                ),
+                notificationThrottleMs = json.optLong(
+                    "notificationThrottleMs", fallback.notificationThrottleMs
+                ),
+                eventThrottleMs = json.optLong("eventThrottleMs", fallback.eventThrottleMs),
+                persistEveryNSteps = json.optInt(
+                    "persistEveryNSteps", fallback.persistEveryNSteps
+                ),
+                healthConnectEnabled = json.optBoolean(
+                    "healthConnectEnabled", fallback.healthConnectEnabled
+                ),
+                healthConnectSyncIntervalMinutes = json.optInt(
+                    "healthConnectSyncIntervalMinutes",
+                    fallback.healthConnectSyncIntervalMinutes
+                ),
+                remoteSyncUrl = json.optStringOrNull("remoteSyncUrl"),
+                remoteSyncHeaders = headers,
+                autoStartOnBoot = json.optBoolean("autoStartOnBoot", fallback.autoStartOnBoot)
+            )
+        }
+
+        private fun JSONObject.optStringOrNull(key: String): String? =
+            if (isNull(key)) null else optString(key).takeIf { it.isNotEmpty() }
+    }
+}
+
+/** Single source of truth for config, shared by the module and the service. */
+class ConfigStore(context: Context) {
+
+    private val prefs = context.applicationContext
+        .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+    @Volatile
+    private var cached: StepTrackerConfig? = null
+
+    @Synchronized
+    fun get(): StepTrackerConfig {
+        cached?.let { return it }
+        val raw = prefs.getString(KEY_CONFIG, null)
+        val parsed = if (raw.isNullOrEmpty()) {
+            StepTrackerConfig()
+        } else {
+            runCatching { StepTrackerConfig.fromJson(JSONObject(raw)) }
+                .getOrElse { StepTrackerConfig() }
+        }
+        cached = parsed.sanitised()
+        return cached!!
+    }
+
+    @Synchronized
+    fun save(config: StepTrackerConfig): StepTrackerConfig {
+        val safe = config.sanitised()
+        cached = safe
+        prefs.edit().putString(KEY_CONFIG, safe.toJson().toString()).apply()
+        return safe
+    }
+
+    fun isInitialized(): Boolean = prefs.contains(KEY_CONFIG)
+
+    companion object {
+        const val PREFS_NAME = "StepTrackerProConfig"
+        private const val KEY_CONFIG = "config_json"
+    }
+}

package/android/src/main/java/com/steptrackerpro/core/StepTrackerCore.kt

@@ -0,0 +1,280 @@
+package com.steptrackerpro.core
+
+import android.content.Context
+import com.steptrackerpro.db.StepRepository
+import com.steptrackerpro.health.HealthConnectManager
+import com.steptrackerpro.sync.SyncScheduler
+import com.steptrackerpro.util.StepEventBus
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Process-wide singleton shared by the React module, the foreground service,
+ * the boot receiver and the workers. Holding one instance is what keeps the
+ * counter consistent when JS is dead but the service is alive.
+ */
+class StepTrackerCore private constructor(context: Context) {
+
+    private val appContext: Context = context.applicationContext
+
+    val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    val configStore = ConfigStore(appContext)
+    val state = StepStateStore(appContext)
+    val metrics = MetricsCalculator(configStore.get())
+    val repository = StepRepository(appContext)
+    val goals = GoalTracker(appContext)
+    val healthConnect = HealthConnectManager(appContext, state)
+
+    val engine = StepCounterEngine(state, metrics).apply {
+        onDayRollover = { closing, newDate -> handleRollover(closing, newDate) }
+    }
+
+    private val lastEventAt = AtomicLong(0L)
+    private val syncMutex = Mutex()
+
+    fun config(): StepTrackerConfig = configStore.get()
+
+    fun updateConfig(config: StepTrackerConfig): StepTrackerConfig {
+        val saved = configStore.save(config)
+        metrics.config = saved
+        SyncScheduler.schedule(appContext, saved)
+        return saved
+    }
+
+    fun isInitialized(): Boolean = configStore.isInitialized()
+
+    // ---- step pipeline ---------------------------------------------------
+
+    /**
+     * Called from the sensor callback for every changed total. Emits a
+     * throttled `stepsChanged`, fires goal events, and flushes to the database
+     * every `persistEveryNSteps`.
+     */
+    fun onStepsChanged(snapshot: StepSnapshot, force: Boolean = false) {
+        val config = config()
+
+        val now = System.currentTimeMillis()
+        val previous = lastEventAt.get()
+        if (force || now - previous >= config.eventThrottleMs) {
+            lastEventAt.set(now)
+            StepEventBus.emit(
+                StepEventBus.Events.STEPS_CHANGED,
+                com.steptrackerpro.util.Bridge.snapshotMap(snapshot)
+            )
+        }
+
+        val percent = metrics.goalPercent(snapshot.steps, config.dailyGoal)
+        if (goals.progressBucketChanged(GoalTracker.TYPE_DAILY, percent)) {
+            StepEventBus.emit(
+                StepEventBus.Events.GOAL_PROGRESS_CHANGED,
+                mapOf(
+                    "type" to GoalTracker.TYPE_DAILY,
+                    "goal" to config.dailyGoal,
+                    "steps" to snapshot.steps,
+                    "progress" to snapshot.goalProgress,
+                    "date" to snapshot.date
+                )
+            )
+        }
+
+        goals.checkDaily(snapshot.date, snapshot.steps, config.dailyGoal)?.let { reached ->
+            emitGoalReached(reached, snapshot.date)
+        }
+
+        if (force || engine.shouldCommit(config.persistEveryNSteps)) {
+            val totals = engine.consumeCommit()
+            scope.launch {
+                repository.saveDay(totals)
+                checkPeriodGoals(totals)
+            }
+        }
+    }
+
+    private fun emitGoalReached(reached: GoalTracker.Reached, date: String) {
+        StepEventBus.emit(
+            StepEventBus.Events.GOAL_REACHED,
+            mapOf(
+                "type" to reached.type,
+                "goal" to reached.goal,
+                "steps" to reached.steps,
+                "date" to date,
+                "timestamp" to System.currentTimeMillis()
+            )
+        )
+    }
+
+    /**
+     * Runs on every commit, so it must not query unconditionally: once a period
+     * goal has fired there is nothing left to learn from summing that period
+     * again, and at `persistEveryNSteps = 10` this path is reached every few
+     * seconds for the length of a walk.
+     */
+    private suspend fun checkPeriodGoals(totals: DayTotals) {
+        val config = config()
+
+        val (weekStart, weekEnd) = DateKeys.calendarWeek()
+        if (config.weeklyGoal > 0 && !goals.alreadyFired(GoalTracker.TYPE_WEEKLY, weekStart)) {
+            goals.checkWeekly(repository.sumSteps(weekStart, weekEnd), config.weeklyGoal)?.let {
+                emitGoalReached(it, totals.date)
+            }
+        }
+
+        val (monthStart, monthEnd) = DateKeys.calendarMonth()
+        if (config.monthlyGoal > 0 && !goals.alreadyFired(GoalTracker.TYPE_MONTHLY, monthStart)) {
+            goals.checkMonthly(repository.sumSteps(monthStart, monthEnd), config.monthlyGoal)?.let {
+                emitGoalReached(it, totals.date)
+            }
+        }
+    }
+
+    /** Persists the closing day, tells JS, and trims history past retention. */
+    private fun handleRollover(closing: DayTotals, newDate: String) {
+        scope.launch {
+            repository.saveDay(closing)
+            // The local date can also move backwards - travelling west across
+            // the date line - in which case the day being adopted is one that
+            // already has steps against it. Restore them so the user does not
+            // land to a counter reading zero halfway through their day.
+            if (newDate < closing.date) {
+                engine.seedActiveDay(newDate, repository.getDay(newDate).steps)
+            }
+            repository.prune(config().historyRetentionDays)
+            StepEventBus.emit(
+                StepEventBus.Events.DAY_CHANGED,
+                mapOf(
+                    "previousDate" to closing.date,
+                    "currentDate" to newDate,
+                    "previousDaySteps" to closing.steps
+                )
+            )
+            if (config().healthConnectEnabled) syncHealthConnect()
+        }
+    }
+
+    /** Writes whatever is in memory to the database. Called before shutdown. */
+    fun flush(): DayTotals {
+        val totals = engine.consumeCommit()
+        scope.launch { repository.saveDay(totals) }
+        return totals
+    }
+
+    fun emitTrackingState(reason: String? = null) {
+        val snapshot = engine.snapshot()
+        StepEventBus.emit(
+            StepEventBus.Events.TRACKING_STATE_CHANGED,
+            mapOf(
+                "state" to snapshot.state.jsValue,
+                "source" to snapshot.source.jsValue,
+                "reason" to reason
+            )
+        )
+    }
+
+    // ---- reads -----------------------------------------------------------
+
+    /** Today's live totals, straight from the counter rather than the database. */
+    fun liveToday(): DayTotals {
+        val snapshot = engine.snapshot()
+        return DayTotals(
+            snapshot.date,
+            snapshot.steps,
+            snapshot.distance,
+            snapshot.calories,
+            false
+        )
+    }
+
+    suspend fun stats(start: String, end: String, goal: Int?): RangeStats {
+        val today = DateKeys.today()
+        val live = if (today in start..end) liveToday() else null
+        return repository.stats(start, end, goal, live)
+    }
+
+    suspend fun dayTotals(date: String): DayTotals =
+        if (date == DateKeys.today()) liveToday() else repository.getDay(date)
+
+    // ---- sync ------------------------------------------------------------
+
+    /** Pushes every unsynced day (plus today) into Health Connect. */
+    suspend fun syncHealthConnect(): Map<String, Any?> = syncMutex.withLock {
+        val config = config()
+        // These three are states the user has to change, not transient faults.
+        // Reporting them as retryable would have the periodic worker back off
+        // and try again forever on a device that will never succeed.
+        if (!config.healthConnectEnabled) {
+            return@withLock syncResult("health_connect", 0, 0, false, "Disabled in config")
+        }
+        if (healthConnect.availability() != HealthConnectManager.Availability.AVAILABLE) {
+            return@withLock syncResult(
+                "health_connect", 0, 0, false, "Health Connect unavailable"
+            )
+        }
+        if (!healthConnect.hasAllPermissions()) {
+            return@withLock syncResult(
+                "health_connect", 0, 0, false, "Health Connect permissions not granted"
+            )
+        }
+
+        // Today is written every time so the mirror stays close to live; older
+        // days are only written while they are still marked unsynced.
+        val today = liveToday()
+        repository.saveDay(today)
+        val pending = repository.unsynced(SyncTarget.HEALTH_CONNECT, limit = 100)
+        // Today first, so its live totals win over the row just written for it.
+        val targets = (listOf(today) + pending).distinctBy { it.date }
+
+        var succeeded = 0
+        var failed = 0
+        val syncedDates = ArrayList<String>(targets.size)
+        for (day in targets) {
+            if (healthConnect.writeDay(day)) {
+                succeeded++
+                // Today stays unsynced: it is still moving.
+                if (day.date != today.date) syncedDates.add(day.date)
+            } else {
+                failed++
+            }
+        }
+        repository.markSynced(SyncTarget.HEALTH_CONNECT, syncedDates)
+        state.lastHealthSyncAt = System.currentTimeMillis()
+
+        // A write that failed against an available, permitted provider is worth
+        // another attempt; nothing else here is.
+        val result = syncResult(
+            "health_connect", succeeded, failed, failed == 0, null, retryable = failed > 0
+        )
+        StepEventBus.emit(StepEventBus.Events.SYNC_COMPLETED, result)
+        result
+    }
+
+    private fun syncResult(
+        target: String,
+        synced: Int,
+        failed: Int,
+        success: Boolean,
+        error: String?,
+        retryable: Boolean = false
+    ): Map<String, Any?> = mapOf(
+        "target" to target,
+        "syncedRecords" to synced,
+        "failedRecords" to failed,
+        "success" to success,
+        "error" to error,
+        "retryable" to retryable
+    )
+
+    companion object {
+        @Volatile
+        private var instance: StepTrackerCore? = null
+
+        fun get(context: Context): StepTrackerCore =
+            instance ?: synchronized(this) {
+                instance ?: StepTrackerCore(context).also { instance = it }
+            }
+    }
+}

package/android/src/main/java/com/steptrackerpro/db/Entities.kt

@@ -0,0 +1,67 @@
+package com.steptrackerpro.db
+
+import androidx.room.ColumnInfo
+import androidx.room.Entity
+import androidx.room.Index
+import androidx.room.PrimaryKey
+
+/**
+ * Append-only-ish log of day totals. One row per day per write cycle target:
+ * the row for a given date is updated in place while that day is active, and
+ * frozen once the day rolls over.
+ */
+@Entity(
+    tableName = "step_history",
+    indices = [
+        Index(value = ["date"], unique = true),
+        Index(value = ["synced"]),
+        Index(value = ["syncedRemote"])
+    ]
+)
+data class StepHistoryEntity(
+    @PrimaryKey(autoGenerate = true)
+    val id: Long = 0L,
+
+    /** yyyy-MM-dd, device local. */
+    val date: String,
+
+    val steps: Int,
+
+    /** Metres. */
+    val distance: Double,
+
+    /** Kilocalories. */
+    val calories: Double,
+
+    /**
+     * 0 = pending, 1 = mirrored to Health Connect. Kept under its original
+     * column name so existing rows migrate without a rewrite.
+     */
+    @ColumnInfo(name = "synced")
+    val syncedHealth: Boolean = false,
+
+    /** 0 = pending, 1 = uploaded to the configured remote endpoint. */
+    @ColumnInfo(name = "syncedRemote", defaultValue = "0")
+    val syncedRemote: Boolean = false,
+
+    @ColumnInfo(name = "createdAt")
+    val createdAt: Long = System.currentTimeMillis(),
+
+    @ColumnInfo(name = "updatedAt")
+    val updatedAt: Long = System.currentTimeMillis()
+)
+
+/**
+ * Rolled-up totals, kept separate so statistics queries never contend with the
+ * hot write path on `step_history`.
+ */
+@Entity(tableName = "daily_summary")
+data class DailySummaryEntity(
+    @PrimaryKey
+    val date: String,
+    val totalSteps: Int,
+    val totalDistance: Double,
+    val totalCalories: Double,
+    @ColumnInfo(name = "updatedAt")
+    val updatedAt: Long = System.currentTimeMillis()
+)