react-native-step-tracker-pro 1.0.0

package/android/src/main/res/values/styles.xml

@@ -0,0 +1,8 @@
+<resources>
+    <style name="StepTrackerPro.Transparent" parent="android:Theme.Translucent.NoTitleBar">
+        <item name="android:windowBackground">@android:color/transparent</item>
+        <item name="android:windowIsTranslucent">true</item>
+        <item name="android:windowNoTitle">true</item>
+        <item name="android:backgroundDimEnabled">false</item>
+    </style>
+</resources>

package/android/src/newarch/java/com/steptrackerpro/StepTrackerProSpec.kt

@@ -0,0 +1,10 @@
+package com.steptrackerpro
+
+import com.facebook.react.bridge.ReactApplicationContext
+
+/**
+ * New architecture shim. `NativeStepTrackerProSpec` is generated by codegen
+ * from `src/NativeStepTrackerPro.ts` at build time.
+ */
+abstract class StepTrackerProSpec internal constructor(context: ReactApplicationContext) :
+    NativeStepTrackerProSpec(context)

package/android/src/oldarch/java/com/steptrackerpro/StepTrackerProSpec.kt

@@ -0,0 +1,60 @@
+package com.steptrackerpro
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * Old architecture shim. Mirrors the signatures codegen produces for the new
+ * architecture so `StepTrackerProModule` compiles unchanged against both.
+ */
+abstract class StepTrackerProSpec internal constructor(context: ReactApplicationContext) :
+    ReactContextBaseJavaModule(context) {
+
+    abstract fun initialize(config: ReadableMap, promise: Promise)
+    abstract fun updateConfig(config: ReadableMap, promise: Promise)
+    abstract fun getConfig(promise: Promise)
+    abstract fun startTracking(promise: Promise)
+    abstract fun pauseTracking(promise: Promise)
+    abstract fun resumeTracking(promise: Promise)
+    abstract fun stopTracking(promise: Promise)
+    abstract fun getTrackingState(promise: Promise)
+    abstract fun isTracking(promise: Promise)
+
+    abstract fun getTodaySteps(promise: Promise)
+    abstract fun getStepsForDate(date: String, promise: Promise)
+    abstract fun getYesterdaySteps(promise: Promise)
+    abstract fun getStatsForRange(startDate: String, endDate: String, promise: Promise)
+    abstract fun getWeeklyStats(options: ReadableMap, promise: Promise)
+    abstract fun getMonthlyStats(options: ReadableMap, promise: Promise)
+    abstract fun getYearlyStats(options: ReadableMap, promise: Promise)
+    abstract fun getHistory(startDate: String, endDate: String, promise: Promise)
+
+    abstract fun resetToday(promise: Promise)
+    abstract fun clearHistory(promise: Promise)
+    abstract fun pruneHistory(retentionDays: Double, promise: Promise)
+
+    abstract fun checkPermissions(promise: Promise)
+    abstract fun requestPermissions(promise: Promise)
+    abstract fun getDeviceCapabilities(promise: Promise)
+    abstract fun openAppSettings(promise: Promise)
+
+    abstract fun isBatteryOptimizationEnabled(promise: Promise)
+    abstract fun requestDisableBatteryOptimization(promise: Promise)
+    abstract fun openBatteryOptimizationSettings(promise: Promise)
+    abstract fun openManufacturerAutoStartSettings(promise: Promise)
+
+    abstract fun getHealthConnectStatus(promise: Promise)
+    abstract fun requestHealthConnectPermissions(promise: Promise)
+    abstract fun openHealthConnectSettings(promise: Promise)
+    abstract fun readHealthConnectSteps(startIso: String, endIso: String, promise: Promise)
+    abstract fun writeHealthConnectSteps(date: String, promise: Promise)
+    abstract fun syncWithHealthConnect(promise: Promise)
+
+    abstract fun getPendingSyncCount(promise: Promise)
+    abstract fun syncNow(promise: Promise)
+
+    abstract fun addListener(eventName: String)
+    abstract fun removeListeners(count: Double)
+}

package/docs/API.md

@@ -0,0 +1,329 @@
+# API reference
+
+Every method returns a promise and rejects with a `StepTrackerError` carrying a
+stable `code`, so you can branch without matching on message strings.
+
+```ts
+import StepTracker, { StepTrackerError } from 'react-native-step-tracker-pro';
+
+try {
+  await StepTracker.startTracking();
+} catch (error) {
+  if ((error as StepTrackerError).code === 'E_PERMISSION_DENIED') { /* ... */ }
+}
+```
+
+Codes: `E_UNSUPPORTED_PLATFORM`, `E_NO_SENSOR`, `E_NOT_INITIALIZED`,
+`E_PERMISSION_DENIED`, `E_SERVICE_START_FAILED`, `E_HEALTH_CONNECT_UNAVAILABLE`,
+`E_HEALTH_CONNECT_DENIED`, `E_DATABASE`, `E_INVALID_CONFIG`, `E_NO_ACTIVITY`,
+`E_UNKNOWN`.
+
+---
+
+## Lifecycle
+
+### `initialize(config?: StepTrackerConfig): Promise<StepSnapshot>`
+
+Persists config natively and reconciles the counter against the current boot and
+date. Idempotent — call it on every app launch, before anything else. Config is
+stored in SharedPreferences, so the foreground service can rebuild it after a
+process restart with no JS running.
+
+### `updateConfig(config: StepTrackerConfig): Promise<StepTrackerConfig>`
+
+Patches config at runtime. Goals and the notification update immediately.
+Changing `height` or `sex` recomputes stride length unless you pass an explicit
+`strideLength`.
+
+### `startTracking(): Promise<StepSnapshot>`
+
+Starts the foreground service. Rejects with `E_PERMISSION_DENIED` if
+`ACTIVITY_RECOGNITION` is missing, `E_NO_SENSOR` if the device has neither step
+sensor.
+
+### `pauseTracking()` / `resumeTracking(): Promise<StepSnapshot>`
+
+The service and notification stay alive; sensor deltas are folded into the
+anchor instead of the total, so paused steps are discarded rather than buffered.
+
+### `stopTracking(): Promise<StepSnapshot>`
+
+Flushes to the database, unregisters the sensors, cancels sync work, kills the
+service, and clears the auto-start-on-boot flag.
+
+### `getTrackingState(): Promise<TrackingState>`
+
+`'idle' | 'running' | 'paused' | 'stopped' | 'unsupported'`.
+
+### `isTracking(): Promise<boolean>`
+
+---
+
+## Reading steps
+
+### `getTodaySteps(): Promise<StepSnapshot>`
+
+```ts
+{
+  date: '2026-09-06',
+  steps: 7431,
+  distance: 5231.4,      // metres
+  calories: 223.1,       // kcal
+  dailyGoal: 10000,
+  goalProgress: 0.7431,  // 0..1
+  goalReached: false,
+  state: 'running',
+  source: 'step_counter',
+  timestamp: 1757145600000
+}
+```
+
+Live from the counter, not the database — correct even if the last flush was
+several steps ago.
+
+### `getYesterdaySteps(): Promise<DayRecord>`
+### `getStepsForDate(date: string): Promise<DayRecord>`
+
+`date` is `yyyy-MM-dd` in the device timezone.
+
+```ts
+{ date: '2026-09-05', steps: 11204, distance: 7887.6, calories: 336.4, synced: true }
+```
+
+### `getWeeklyStats(options?)` / `getMonthlyStats(options?)` / `getYearlyStats(options?)`
+
+```ts
+type RangeOptions = {
+  mode?: 'calendar' | 'rolling'; // default 'calendar'
+  offset?: number;               // 0 = current, 1 = previous. Calendar mode only.
+};
+```
+
+`calendar` snaps to the Monday-anchored ISO week, the calendar month, or the
+calendar year. `rolling` uses the last 7 / 30 / 365 days ending today.
+
+```ts
+{
+  startDate: '2026-08-31',
+  endDate: '2026-09-06',
+  totalSteps: 54210,
+  totalDistance: 38160.4,
+  totalCalories: 1630.2,
+  averageSteps: 9035,       // over elapsed days, not the whole window
+  activeDays: 6,
+  bestDay: { date: '2026-09-03', steps: 14002, ... },
+  days: [ /* zero-filled, ascending, today merged live */ ],
+  goal: 70000,
+  goalProgress: 0.774
+}
+```
+
+`averageSteps` divides by elapsed days so a half-finished month is not diluted
+by days that have not happened yet.
+
+### `getStatsForRange(startDate, endDate): Promise<RangeStats>`
+### `getHistory(startDate, endDate): Promise<DayRecord[]>`
+
+Raw rows, zero-filled. Use this to draw charts; use `getStatsForRange` when you
+want the aggregates computed for you.
+
+---
+
+## Writes
+
+### `resetToday(): Promise<boolean>`
+
+Zeroes today's counter and re-arms goal events. History is untouched. Meant for
+QA builds.
+
+### `clearHistory(): Promise<boolean>`
+### `pruneHistory(retentionDays?): Promise<number>`
+
+Deletes rows older than the window and returns how many were removed. Runs
+automatically at midnight and once a day via WorkManager, using
+`historyRetentionDays` from config.
+
+---
+
+## Permissions
+
+### `requestPermissions(): Promise<PermissionStatus>`
+
+Shows the runtime dialogs for `ACTIVITY_RECOGNITION` and, on Android 13+,
+`POST_NOTIFICATIONS`. Needs a foreground activity; rejects with `E_NO_ACTIVITY`
+otherwise.
+
+```ts
+{
+  activityRecognition: true,
+  postNotifications: true,
+  foregroundServiceHealth: true, // always true below API 34
+  allGranted: true
+}
+```
+
+`allGranted` deliberately ignores `POST_NOTIFICATIONS` — denying it hides the
+notification but does not stop counting.
+
+### `checkPermissions(): Promise<PermissionStatus>`
+### `getDeviceCapabilities(): Promise<DeviceCapabilities>`
+
+```ts
+{ hasStepCounter: true, hasStepDetector: true, supported: true,
+  sdkInt: 35, manufacturer: 'samsung', model: 'SM-S928B' }
+```
+
+Check this before showing a step UI at all. A handful of low-end devices and
+most emulators have no step hardware.
+
+### `openAppSettings(): Promise<boolean>`
+
+---
+
+## Battery
+
+### `isBatteryOptimizationEnabled(): Promise<boolean>`
+
+True means the OS is still applying Doze restrictions to your app.
+
+### `requestDisableBatteryOptimization(): Promise<boolean>`
+
+Shows the system exemption dialog. Requires
+`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` and an eligible Play use case — read
+[PLAY_STORE_COMPLIANCE.md](PLAY_STORE_COMPLIANCE.md) first.
+
+### `openBatteryOptimizationSettings(): Promise<boolean>`
+
+Policy-safe alternative: opens the settings list and lets the user choose.
+
+### `openManufacturerAutoStartSettings(): Promise<boolean>`
+
+Best-effort deep link into Xiaomi / Oppo / Vivo / Huawei autostart screens,
+falling back to app info. On those skins this matters more than Doze.
+
+---
+
+## Health Connect
+
+### `getHealthConnectStatus(): Promise<HealthConnectStatus>`
+
+```ts
+{ available: true, requiresUpdate: false, granted: false, grantedPermissions: [] }
+```
+
+### `requestHealthConnectPermissions(): Promise<HealthConnectStatus>`
+
+Launches the provider's permission sheet through a transparent activity. If the
+user has permanently denied, the sheet does not appear — fall back to
+`openHealthConnectSettings()`.
+
+### `readHealthConnectSteps(startIso, endIso)`
+
+ISO-8601 instants. Aggregated per day across every source Health Connect knows
+about, so it includes a paired watch, not just your app.
+
+```ts
+{ totalSteps: 82310, records: [ { date, steps, distance, calories, synced } ] }
+```
+
+### `writeHealthConnectSteps(date: string): Promise<boolean>`
+### `syncWithHealthConnect(): Promise<SyncEvent>`
+
+Writes are idempotent: each record carries a stable `clientRecordId`
+(`stp-steps-2026-09-06`), so re-syncing a day replaces the previous record
+rather than stacking duplicates.
+
+### `openHealthConnectSettings(): Promise<boolean>`
+
+---
+
+## Sync
+
+### `syncNow(): Promise<SyncEvent[]>`
+
+Runs Health Connect sync inline and queues the remote upload. The remote result
+arrives later on the `syncCompleted` event, since WorkManager waits for a
+network.
+
+### `getPendingSyncCount(): Promise<number>`
+
+Days written locally but not yet mirrored. Non-zero offline is normal.
+
+---
+
+## Events
+
+```ts
+const sub = StepTracker.addListener('stepsChanged', (data) => console.log(data.steps));
+sub.remove();
+
+StepTracker.removeListener('goalReached'); // all listeners for one event
+StepTracker.removeListener();              // everything
+```
+
+| Event | Payload |
+|---|---|
+| `stepsChanged` | `StepSnapshot`. Throttled by `eventThrottleMs` (default 500 ms). |
+| `goalReached` | `{ type: 'daily' \| 'weekly' \| 'monthly', goal, steps, date, timestamp }`. Fires at most once per period. |
+| `goalProgressChanged` | `{ type, goal, steps, progress, date }`. Fires when the whole-percent bucket changes. |
+| `trackingStateChanged` | `{ state, source, reason }`. `reason` is `'boot'`, `'paused'`, `'no_sensor'`, etc. |
+| `dayChanged` | `{ previousDate, currentDate, previousDaySteps }`. Refetch your stats here. |
+| `syncCompleted` | `{ target: 'health_connect' \| 'remote', syncedRecords, failedRecords, success, error? }` |
+| `error` | `{ code, message }`. Emitted from the service, where there is no promise to reject. |
+
+Events fire only while a React instance is alive. The service keeps counting and
+writing to the database regardless — on resume, call `getTodaySteps()` rather
+than replaying missed events. `useStepTracker` already does this.
+
+---
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `height` | 170 | cm, drives stride length |
+| `weight` | 70 | kg, drives calories |
+| `strideLength` | derived | metres; overrides the height-based estimate |
+| `sex` | `'unspecified'` | picks the stride coefficient only |
+| `dailyGoal` | 10000 | |
+| `weeklyGoal` | `dailyGoal × 7` | |
+| `monthlyGoal` | `dailyGoal × 30` | |
+| `calorieCoefficient` | 0.57 | kcal per kg per km |
+| `historyRetentionDays` | 35 | set 31 for a one-month window |
+| `notificationTitle` / `notificationText` | built-in | tokens: `{steps}` `{distance}` `{calories}` `{percent}` `{goal}` |
+| `notificationIcon` | bundled | drawable name in your app |
+| `notificationChannelName` | "Step tracking" | shown in Android settings |
+| `notificationActions` | `true` | Pause/Resume/Open buttons |
+| `notificationThrottleMs` | 1000 | minimum ms between notification redraws |
+| `eventThrottleMs` | 500 | minimum ms between `stepsChanged` events |
+| `persistEveryNSteps` | 10 | database flush cadence |
+| `healthConnectEnabled` | `true` | |
+| `healthConnectSyncIntervalMinutes` | 30 | clamped to WorkManager's 15-minute floor; 0 disables |
+| `remoteSyncUrl` | — | optional HTTPS endpoint for unsynced days |
+| `remoteSyncHeaders` | `{}` | e.g. auth headers |
+| `autoStartOnBoot` | `true` | |
+
+---
+
+## Hooks
+
+### `useStepTracker(options)`
+
+```tsx
+const {
+  snapshot, state, ready, error,
+  start, pause, resume, stop, refresh, requestPermissions,
+} = useStepTracker({ dailyGoal: 10000, autoStart: true, onGoalReached: (e) => {} });
+```
+
+Initialises once, subscribes to `stepsChanged` and `trackingStateChanged`, and
+re-reads the snapshot when the app returns to the foreground. Extra options:
+`autoStart` (default false) and `refreshOnForeground` (default true).
+
+### `useStepStats(period, options?)`
+
+```tsx
+const { stats, loading, error, reload } = useStepStats('week');
+```
+
+`period` is `'week' | 'month' | 'year'`. Reloads automatically on `dayChanged`.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,203 @@
+# Architecture
+
+```
+                       ┌──────────────────────────┐
+   JS  ────────────────│  StepTracker.ts (typed)  │
+                       └────────────┬─────────────┘
+                                    │ Turbo Module
+                       ┌────────────▼─────────────┐
+                       │  StepTrackerProModule    │  thin: validate, delegate,
+                       └────────────┬─────────────┘  convert
+                                    │
+     ┌──────────────────────────────▼───────────────────────────────┐
+     │                      StepTrackerCore                         │
+     │        (process-wide singleton: config, engine, goals)       │
+     └───┬──────────────┬──────────────┬───────────────┬────────────┘
+         │              │              │               │
+ ┌───────▼──────┐ ┌─────▼──────┐ ┌─────▼───────┐ ┌─────▼─────────┐
+ │ StepCounter  │ │StepRepo/   │ │HealthConnect│ │  StepEventBus │
+ │   Engine     │ │  Room      │ │   Manager   │ │               │
+ └───────▲──────┘ └────────────┘ └─────────────┘ └───────────────┘
+         │
+ ┌───────┴────────────────┐        ┌──────────────┐
+ │  StepTrackerService    │◄───────│ BootReceiver │
+ │  (foreground, health)  │        └──────────────┘
+ └────────────────────────┘
+```
+
+The module is the only piece that dies with JS. Everything below it keeps
+running, which is why the module holds no state of its own.
+
+## Why a singleton
+
+The service and the React module live in the same process. Sharing one
+`StepTrackerCore` means the counter cannot fork: a `getTodaySteps()` call from
+JS reads the exact same engine the sensor callback just wrote to. Anything
+routed through IPC or broadcasts would drift.
+
+## The counting maths
+
+`TYPE_STEP_COUNTER` reports steps since the device booted. The day total is:
+
+```
+stepsToday = anchorSteps + (rawValue − anchorValue)
+```
+
+`anchorValue` is the raw reading that corresponded to `anchorSteps`. The anchor
+is re-pinned whenever the meaning of `rawValue` changes.
+
+### Reboot
+
+The counter restarts at zero. Two signals have to agree before the steps since
+boot are claimed:
+
+1. The approximate boot timestamp — `System.currentTimeMillis() −
+   SystemClock.elapsedRealtime()` — moved by more than 60 seconds.
+2. The reading itself went backwards, below `lastRawValue`.
+
+The boot timestamp on its own is not enough, because it is derived from the wall
+clock: a manual clock change, or an NTP correction on a phone whose RTC was
+wrong at boot, moves it by hours without the counter restarting. Acting on that
+alone would add the day's steps to themselves.
+
+Once a real reboot is established:
+
+- **Boot happened today.** The steps taken between boot and the first sample are
+  real and unclaimed, so `anchorValue = 0` and they are picked up.
+- **Boot happened on a previous day.** Those steps straddle midnight and cannot
+  be attributed, so `anchorValue = rawValue` and they are dropped. Losing a few
+  steps beats moving yesterday's steps into today.
+
+### Counter reset without a reboot
+
+Some OEM sensor HALs restart the counter when the last listener unregisters.
+Detected as `rawValue` dropping below `lastRawValue`, the previous reading; the
+anchor is re-pinned at the current reading with `anchorSteps = stepsToday`, so
+the running total is preserved and nothing is double counted.
+
+Comparing against `anchorValue` instead would miss it entirely for the whole of
+any day the device booted on, because the anchor is `0` for that day and no
+valid reading is below zero.
+
+### Timezone moving backwards
+
+`rollDateIfNeeded()` fires on any change of the local date key, in either
+direction. Travelling west across the date line moves it backwards: the day
+being left is persisted but is not finished, and the day being adopted may
+already have steps stored against it, so `StepTrackerCore` re-seeds the live
+counter from the database instead of letting it report zero mid-day.
+
+### Midnight
+
+`rollDateIfNeeded()` finalises the previous day into Room, emits `dayChanged`,
+prunes past the retention window, pushes the closed day into Health Connect, and
+re-pins with `anchorSteps = 0`.
+
+Sensor batching is set to zero latency, so a sample delivered after midnight for
+steps taken before it is not a practical concern. If you raise
+`MAX_REPORT_LATENCY_US` to save battery, that trade-off comes back.
+
+### Process death
+
+Counter state is written to SharedPreferences on every sensor batch
+(`StepStateStore.writeCounterState`, one atomic edit). If the OS kills the
+service, `START_STICKY` restarts it, `reconcile()` reloads the anchor, and the
+first sample recovers everything the hardware counted while the process was
+gone. There is no window in which steps are lost — that is the whole reason for
+using `TYPE_STEP_COUNTER` instead of `TYPE_STEP_DETECTOR`.
+
+A restart with a null intent is the OS bringing the service back, not a user
+action, so it restores rather than starts: `setPaused()` ignores a no-op
+transition, and a pause the user set before the process died survives it. Arming
+the resume re-anchor on every start would discard exactly the steps this
+paragraph promises to recover.
+
+### The detector fallback
+
+`TYPE_STEP_DETECTOR` fires once per step and carries no cumulative value, so it
+increments the total directly. On devices with no step counter, steps taken
+while the process is dead are genuinely lost. `getDeviceCapabilities()` tells
+you which sensor you are on.
+
+## Storage
+
+Two Room tables:
+
+- `step_history` — `id`, `date` (unique), `steps`, `distance`, `calories`,
+  `synced`, `createdAt`, `updatedAt`. Hot write path.
+- `daily_summary` — `date` (PK), `totalSteps`, `totalDistance`,
+  `totalCalories`, `updatedAt`. Rolled-up mirror of the same values, written in
+  the same transaction as `step_history`.
+
+`saveDay()` refuses to lower an existing day's count. A re-anchored counter can
+briefly report fewer steps than were already committed; ignoring that write is
+cheaper than reasoning about it later. Deliberate writes that must be allowed to
+lower a day — `resetToday()` — go through `overwriteDay()` instead, otherwise
+the old total would survive the reset and history would disagree with the live
+counter permanently.
+
+Health Connect and the remote endpoint track their progress in **separate**
+columns (`synced` and `syncedRemote`). Sharing one flag let whichever sink ran
+first hide the row from the other, so a day uploaded remotely would never reach
+Health Connect.
+
+Counter state deliberately lives in SharedPreferences, not Room: it is written
+constantly and must be readable synchronously from `onStartCommand` before any
+coroutine gets a chance to run. It also means a corrupt database costs you
+history, never the live count.
+
+Flush cadence is `persistEveryNSteps` (default 10) plus a forced flush on pause,
+stop, task removal and destroy.
+
+## Foreground service
+
+Declared `android:foregroundServiceType="health"`, which on Android 14+ requires
+`FOREGROUND_SERVICE_HEALTH` and is passed to `startForeground`. Below 34 the
+two-argument overload is used, so no unknown type reaches an older platform.
+
+`startForeground` is called first thing in `onStartCommand`, before anything
+that can throw, or the OS raises `ForegroundServiceDidNotStartInTimeException`.
+
+`stopWithTask="false"` keeps the service alive when the user swipes the app
+away — that is the whole point. `onTaskRemoved` just flushes.
+
+Notification updates are throttled to `notificationThrottleMs` and skipped when
+the step count has not changed, so a walk does not redraw the shade sixty times
+a minute.
+
+## Events
+
+`StepEventBus` is a plain in-process pub/sub. The module subscribes on
+construction and unsubscribes on `invalidate()`. Emission is a no-op when no
+React instance is active — the service does not care whether anyone is
+listening, it keeps writing to storage either way.
+
+`stepsChanged` is throttled by `eventThrottleMs`. `goalProgressChanged` fires
+only when the whole-percent bucket moves. `goalReached` is keyed on the period's
+start date, so it fires once per day/week/month and rearms by itself.
+
+## Sync
+
+Three WorkManager jobs:
+
+| Worker | Constraint | Period |
+|---|---|---|
+| `HealthConnectSyncWorker` | none | `healthConnectSyncIntervalMinutes`, floor 15 |
+| `RemoteSyncWorker` | network connected | 1 hour, exponential backoff |
+| `RetentionWorker` | none | daily |
+
+Health Connect sync has no network constraint because Health Connect is entirely
+on-device. Offline sync is still sync. Only the optional `remoteSyncUrl` upload
+waits for connectivity, and nothing else waits on it.
+
+Today's row is written to Health Connect on every pass but left `synced = 0`,
+because it is still moving. Closed days are marked synced once written.
+
+## Threading
+
+- Sensor callbacks arrive on the sensor thread. Engine mutation is
+  `@Synchronized`.
+- Database and Health Connect work runs on `Dispatchers.IO` from the core's
+  `SupervisorJob` scope, so one failed write cannot cancel the pipeline.
+- Bridge conversion happens on whichever thread resolves the promise; the module
+  never touches the engine off-lock.