reis-mobile 0.7.3 → 0.9.0

package/skills/mobile-offline-sync/references/android.md

@@ -0,0 +1,123 @@
+# Offline sync on native Android
+
+Android ships every piece this needs: Room for the store and the outbox, WorkManager for a drain that survives process death and reboot, and `ConnectivityManager` for the trigger. The mistakes are almost always in how they are combined, not in the APIs themselves.
+
+## The store and the outbox
+
+Room, with the sync state on the entity and a separate outbox table:
+
+```kotlin
+@Entity(tableName = "orders")
+data class OrderEntity(
+    @PrimaryKey val id: String,            // client-generated UUID
+    val total: Long,
+    val syncStatus: SyncStatus,            // SYNCED, PENDING, FAILED
+    val serverVersion: String?,            // ETag or version from the last successful fetch
+    val updatedAt: Long,
+)
+
+@Entity(tableName = "outbox")
+data class OutboxEntry(
+    @PrimaryKey val id: String,            // operation UUID = idempotency key
+    val entityType: String,
+    val entityId: String,
+    val operation: String,                 // CREATE | UPDATE | DELETE
+    val payloadJson: String,               // changed fields only
+    val attempts: Int = 0,
+    val nextAttemptAt: Long,
+    val lastError: String? = null,
+    val createdAt: Long,
+)
+```
+
+Write the optimistic change and the outbox entry inside one `@Transaction` DAO method. Expose reads as `Flow<List<OrderEntity>>` so the UI updates when either the optimistic write or the sync lands.
+
+For paged data backed by a server, Paging 3's `RemoteMediator` is the supported pattern: the `PagingSource` reads Room, the mediator fills Room from the network, and the UI never sees a network state machine.
+
+## The drain
+
+`WorkManager`, as **unique** work, with backoff delegated to the platform:
+
+```kotlin
+val request = OneTimeWorkRequestBuilder<SyncWorker>()
+    .setConstraints(Constraints(requiredNetworkType = NetworkType.CONNECTED))
+    .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
+    .build()
+
+WorkManager.getInstance(context).enqueueUniqueWork(
+    "sync-outbox",
+    ExistingWorkPolicy.KEEP,     // a burst of reconnect events must not queue five drains
+    request,
+)
+```
+
+Inside the worker:
+
+- Process entries **in order per entity**; parallelize only across unrelated entities.
+- Return `Result.retry()` for transient failures — WorkManager applies the backoff policy and re-runs after process death or reboot. Returning `Result.failure()` discards the work.
+- Handle a permanently rejected entry by dead-lettering it in the database and **continuing**, not by failing the whole worker.
+- Enqueue the drain with `ExistingWorkPolicy.KEEP` (or `APPEND_OR_REPLACE` when ordering across enqueues matters) so reconnect bursts do not start concurrent drains.
+- `setExpedited` only when the user is waiting; an ordinary background drain does not qualify and the quota is limited.
+
+Constraints and foreground-service rules are in [background.md](../../mobile-performance/references/background.md). A periodic sync has a 15-minute floor and is never exact.
+
+## Idempotency over Retrofit/OkHttp
+
+Put the entry's id on the request as the idempotency key, and make sure **OkHttp's own retries do not hide a failure you need to record**:
+
+```kotlin
+@POST("orders")
+suspend fun createOrder(
+    @Header("Idempotency-Key") key: String,
+    @Body body: OrderPayload,
+): Response<OrderDto>
+```
+
+`retryOnConnectionFailure` (on by default) retries connection-level failures transparently. That is safe *only* because the key makes the call idempotent; without server-side key handling it is a duplicate-creation mechanism. An `Interceptor` that retries on 5xx compounds the problem — keep retry scheduling in WorkManager, where it survives the process, rather than in an interceptor, where it does not.
+
+## Conflict detection
+
+Send the version you based the edit on and let the server reject:
+
+```kotlin
+@PUT("orders/{id}")
+suspend fun updateOrder(
+    @Path("id") id: String,
+    @Header("If-Match") version: String,
+    @Header("Idempotency-Key") key: String,
+    @Body body: Map<String, Any?>,       // changed fields only
+): Response<OrderDto>
+```
+
+A `412 Precondition Failed` is the conflict signal; apply the strategy chosen per entity in the skill's §6. If the API has no ETag or version field, record it as a finding — conflicts are undetectable and the design is last-write-wins by accident.
+
+## Connectivity as a trigger
+
+```kotlin
+connectivityManager.registerNetworkCallback(
+    NetworkRequest.Builder()
+        .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+        .addCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)   // not just "an interface"
+        .build(),
+    callback,
+)
+```
+
+`NET_CAPABILITY_VALIDATED` excludes most captive portals, which a plain `NET_CAPABILITY_INTERNET` check does not. Even so, treat it as a hint: enqueue the WorkManager request and let its `NetworkType.CONNECTED` constraint be the real gate. Also drain on `ON_START` of the process lifecycle and on explicit user refresh.
+
+## Testing
+
+- **Room** has an in-memory builder (`Room.inMemoryDatabaseBuilder`), so ordering, collapsing, dead-lettering and transaction atomicity are JVM unit tests.
+- **WorkManager** ships `androidx.work:work-testing`: `WorkManagerTestInitHelper` with a `SynchronousExecutor` plus `TestDriver.setAllConstraintsMet`/`setInitialDelayMet` makes the drain deterministic, including the retry path.
+- **The API** should be faked at the repository boundary, or served by MockWebServer when you need real HTTP semantics — MockWebServer can return a 200 the client never receives (`SocketPolicy.DISCONNECT_AFTER_REQUEST`), which is exactly the lost-response case.
+- **Device conditions:** the emulator's cellular/network delay and speed settings, `adb shell svc wifi disable` / `svc data disable`, and `adb shell cmd connectivity airplane-mode enable` for a scripted offline window.
+- Process death: `adb shell am kill <package>` mid-drain, then relaunch and assert exactly one server-side record.
+
+## Official documentation
+
+- Offline-first app architecture: https://developer.android.com/topic/architecture/data-layer/offline-first
+- Room: https://developer.android.com/training/data-storage/room
+- WorkManager: https://developer.android.com/topic/libraries/architecture/workmanager
+- Testing WorkManager: https://developer.android.com/topic/libraries/architecture/workmanager/how-to/integration-testing
+- Monitoring connectivity status: https://developer.android.com/training/monitoring-device-state/connectivity-status-type
+- Paging with a network and database: https://developer.android.com/topic/libraries/architecture/paging/v3-network-db

package/skills/mobile-offline-sync/references/flutter.md

@@ -0,0 +1,103 @@
+# Offline sync in Flutter
+
+Flutter has no built-in persistence, so the first decision is the store. The second is where the sync engine lives: it must outlive any widget, so it belongs in a repository/service registered in the app's DI container — never in a `State` object, and never behind a `ChangeNotifier` that a route disposes.
+
+## The local store
+
+| Package | Fits when | Notes |
+|---|---|---|
+| `drift` | You want SQL, migrations and typed reactive queries | `Stream` per query out of the box; the usual default for a real offline store |
+| `sqflite` | You want SQLite with no code generation | You write the SQL, the mapping and the change notifications yourself |
+| `objectbox`, `isar`, `realm` | Object graphs, heavy local querying | Check the package's current maintenance status and platform support before adopting it |
+| `hive` / `shared_preferences` | Key–value settings, a small cache | Not a store for records you query, filter or sync per field |
+| `cloud_firestore` | The backend is Firestore | Offline persistence and conflict handling are built in; see [mobile-firebase](../../mobile-firebase/SKILL.md) |
+
+Whatever the choice, model the sync state as columns on the record — `syncStatus`, `serverVersion`, `updatedAt`, `lastError` — and expose reads as `Stream`s so the UI reflects an applied mutation without a refresh call.
+
+## The outbox
+
+A table, not a list:
+
+```dart
+// drift
+class Outbox extends Table {
+  TextColumn get id => text()();                       // client UUID = idempotency key
+  TextColumn get entityType => text()();
+  TextColumn get entityId => text()();
+  TextColumn get operation => text()();                // create | update | delete
+  TextColumn get payload => text()();                  // JSON of changed fields only
+  IntColumn  get attempts => integer().withDefault(const Constant(0))();
+  DateTimeColumn get nextAttemptAt => dateTime()();
+  TextColumn get lastError => text().nullable()();
+  DateTimeColumn get createdAt => dateTime()();
+  @override Set<Column> get primaryKey => {id};
+}
+```
+
+Enqueue the outbox entry and apply the optimistic local change **in one transaction**. If they are separate writes, a crash between them leaves the UI showing an edit that will never be sent, or sends an edit the UI never showed.
+
+## Draining
+
+```dart
+Future<void> drain() async {
+  if (_draining) return;            // single-flight: reconnect events arrive in bursts
+  _draining = true;
+  try {
+    for (final entry in await _outbox.dueEntriesInOrder()) {
+      try {
+        await _api.send(entry, idempotencyKey: entry.id);
+        await _db.transaction(() async {
+          await _outbox.delete(entry.id);
+          await _records.markSynced(entry.entityId);
+        });
+      } on ApiException catch (e) when (e.isPermanent) {
+        await _outbox.deadLetter(entry.id, e.message);   // do not block the queue
+      } on Exception catch (e) {
+        await _outbox.scheduleRetry(entry.id, backoffFor(entry.attempts + 1), e.toString());
+        if (e is SocketException) break;                 // offline again: stop early
+      }
+    }
+  } finally {
+    _draining = false;
+  }
+}
+```
+
+Points that reviews catch: the `_draining` guard, deleting the entry only after the call returned, doing the delete and the record update in one transaction, and breaking out of the loop when the device is offline instead of failing every remaining entry and burning its attempt count.
+
+## Triggers and connectivity
+
+- `connectivity_plus` reports the **interface**, not reachability — Wi-Fi with a captive portal reports Wi-Fi. Use its stream as a trigger to try, and treat a successful request as the only proof. `internet_connection_checker_plus` adds an actual reachability probe if you want one, but a real API call is just as good a probe.
+- `WidgetsBindingObserver.didChangeAppLifecycleState` → drain on `resumed`.
+- Background drains go through the `workmanager` plugin (or an equivalent) with the platform constraints from [background.md](../../mobile-performance/references/background.md) — remember the background isolate has no access to your DI container and must build its own, and that iOS gives no guaranteed schedule.
+- Never a `Timer.periodic`.
+
+## Retries
+
+Dart has no built-in backoff. Either use `package:retry` or compute it yourself, and always add jitter:
+
+```dart
+Duration backoffFor(int attempt) {
+  final base = Duration(seconds: 1 << attempt.clamp(0, 6));  // 1s … 64s
+  final jitter = Random().nextInt(base.inMilliseconds ~/ 2);
+  return base + Duration(milliseconds: jitter);
+}
+```
+
+Retry on `SocketException`, `TimeoutException`, and 5xx/408/429. Do not retry other 4xx — dead-letter them. If the HTTP client is Dio, `dio_smart_retry` or a custom `Interceptor` can hold this, but keep the *scheduling* in the outbox: an interceptor that retries in-process loses the retry when the app is killed.
+
+## Testing the failure cases
+
+- Fake the API layer, not `http`: a `FakeApi` that can return success-after-committing (case 2 in the skill's §9) and a stale-version conflict (case 4) makes those tests deterministic. Mocking at the socket level cannot express "the server committed but the response was lost".
+- `drift` runs on an in-memory database (`NativeDatabase.memory()`), so outbox behaviour — ordering, collapsing, dead-lettering, transaction atomicity — is a fast unit test with no device.
+- Process-death (case 1) is an integration test: enqueue, close the database, reopen it, drain.
+- Use `fakeAsync` or an injected clock for backoff timing; never `await Future.delayed` in tests.
+- Device-level network throttling: the iOS Network Link Conditioner and the Android emulator's network profile settings.
+
+## Official documentation
+
+- Flutter persistence cookbook: https://docs.flutter.dev/cookbook/persistence
+- drift: https://drift.simonbinder.eu/
+- connectivity_plus: https://pub.dev/packages/connectivity_plus
+- workmanager: https://pub.dev/packages/workmanager
+- Cloud Firestore offline data: https://firebase.google.com/docs/firestore/manage-data/enable-offline

package/skills/mobile-offline-sync/references/ios.md

@@ -0,0 +1,103 @@
+# Offline sync on native iOS
+
+iOS gives you two very different routes: **let the system sync for you** with Core Data + CloudKit, or **own the sync** with a local store, an outbox and `URLSession`. Choosing the first when the backend is not CloudKit, or hand-rolling the second when CloudKit would have done, is the most expensive mistake in this area.
+
+## Choose the route first
+
+| Route | Fits when |
+|---|---|
+| `NSPersistentCloudKitContainer` (Core Data + CloudKit) | Apple-only product, per-user private data, no custom backend. Apple handles transport, retries, merge policy and multi-device |
+| SwiftData with CloudKit | Same, on a newer API surface; check the deployment target and the feature gaps against Core Data before committing |
+| Local store + your own outbox | There is a REST/GraphQL backend, or Android/web clients share the data. This is the rest of this document |
+| A sync SDK (Firestore, Realm/Atlas Device Sync, PowerSync…) | The backend is that product; offline behaviour comes with it — read its conflict rules rather than inventing your own |
+
+## The local store
+
+- **Core Data** or **SwiftData** for object graphs with relationships and change notification. Enable `NSPersistentHistoryTrackingKey` when a background context or an extension writes, so the UI context can merge remote-ish changes correctly.
+- **GRDB** or raw SQLite when you want SQL, explicit migrations and value types; `ValueObservation` gives reactive reads.
+- `UserDefaults` is for settings. It is not a store for syncable records, and it is not transactional.
+
+Keep sync state on the record: `syncStatus`, `serverVersion` (ETag), `updatedAt`, `lastError`.
+
+## The outbox
+
+A table/entity, written **in the same context save** as the optimistic change:
+
+```swift
+struct OutboxEntry: Codable, Identifiable {
+    let id: UUID                  // operation id = idempotency key
+    let entityType: String
+    let entityID: String
+    let operation: Operation      // create / update / delete
+    let payload: Data             // changed fields only
+    var attempts: Int
+    var nextAttemptAt: Date
+    var lastError: String?
+    let createdAt: Date
+}
+```
+
+In Core Data, perform the optimistic write and the outbox insert on one background context and save once. Two saves mean a crash can leave one without the other.
+
+Use an actor for the drain so concurrent triggers cannot interleave:
+
+```swift
+actor SyncEngine {
+    private var isDraining = false
+
+    func drain() async {
+        guard !isDraining else { return }
+        isDraining = true
+        defer { isDraining = false }
+
+        for entry in await outbox.dueEntriesInOrder() {
+            do {
+                try await api.send(entry, idempotencyKey: entry.id.uuidString)
+                try await store.confirm(entry)          // delete entry + mark record synced, one save
+            } catch let error as APIError where error.isPermanent {
+                try? await outbox.deadLetter(entry, reason: error.message)
+            } catch {
+                try? await outbox.scheduleRetry(entry, after: backoff(entry.attempts + 1))
+                if error.isOffline { break }
+            }
+        }
+    }
+}
+```
+
+## URLSession
+
+- **`waitsForConnectivity`** on the session configuration makes a request wait for connectivity instead of failing immediately — useful for a user-initiated send, but it does not replace the outbox: the app can still be terminated while waiting.
+- **A background configuration** (`URLSessionConfiguration.background(withIdentifier:)`) hands the transfer to the system, which continues it while the app is suspended and relaunches the app to deliver completion. Use it for uploads and downloads of files; it is not suited to a chatty JSON queue, and the completion handler must work with no UI state in memory.
+- Set `Idempotency-Key` from the entry id on every mutating request, and `If-Match` with the stored ETag on updates. A `412` is the conflict signal.
+- `URLSession` does not retry application-level failures. Schedule retries from the outbox, not by recursing in the completion handler.
+
+## Triggers
+
+- **Foreground:** `scenePhase` becoming `.active`, or `UIApplication.didBecomeActiveNotification`.
+- **Connectivity:** `NWPathMonitor` (Network framework). `path.status == .satisfied` means a usable interface, not a reachable server — use it as a hint and let the request be the proof. Check `path.isExpensive` and `path.isConstrained` before draining a large queue on cellular or Low Data Mode.
+- **Background:** `BGAppRefreshTaskRequest` for short opportunistic drains, `BGProcessingTaskRequest` for a large one while charging, and a background `URLSession` for transfers that must complete. There is no guaranteed schedule — see [background.md](../../mobile-performance/references/background.md). Always schedule the next request at the end of a run, set the `expirationHandler`, and call `setTaskCompleted(success:)`.
+- **Never** a `Timer` that polls.
+
+## Conflict resolution
+
+With your own backend: store the ETag, send `If-Match`, apply the per-entity strategy from the skill's §6 on `412`.
+
+With Core Data and CloudKit, the merge policy *is* the strategy, and it is not always the one you want: `NSMergeByPropertyObjectTrumpMergePolicy` keeps local values per property, `...StoreTrumpMergePolicy` keeps the persisted ones, and `NSOverwriteMergePolicy`/`NSRollbackMergePolicy` are whole-object. Choose it explicitly on each context rather than inheriting `NSErrorMergePolicy` and discovering conflicts as save failures in production.
+
+## Testing
+
+- Put the network behind a protocol and inject a fake in tests; `URLProtocol` subclassing works when you need the real `URLSession` path, including a response that arrives after the server committed.
+- Core Data with an in-memory store (`NSInMemoryStoreType`, or `/dev/null` for a SQLite store) makes outbox ordering, collapsing and transaction atomicity fast unit tests. SwiftData takes an in-memory `ModelConfiguration`.
+- Inject a clock rather than reading `Date()` in backoff and expiry logic, so timing is deterministic.
+- Device conditions: the **Network Link Conditioner** (Settings → Developer on device, or the Additional Tools package on the Mac) for loss and latency profiles, and Xcode's simulated network conditions in the debug gauges.
+- Background task runs can be triggered from the debugger with the documented LLDB call to `_simulateLaunchForTaskWithIdentifier:` — the only practical way to test a `BGTask` path without waiting for the system.
+
+## Official documentation
+
+- Core Data: https://developer.apple.com/documentation/coredata
+- Mirroring a Core Data store with CloudKit: https://developer.apple.com/documentation/coredata/mirroring_a_core_data_store_with_cloudkit
+- SwiftData: https://developer.apple.com/documentation/swiftdata
+- NWPathMonitor: https://developer.apple.com/documentation/network/nwpathmonitor
+- Downloading files in the background: https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background
+- Background tasks: https://developer.apple.com/documentation/backgroundtasks

package/skills/mobile-offline-sync/references/kotlin-multiplatform.md

@@ -0,0 +1,114 @@
+# Offline sync in Kotlin Multiplatform
+
+Offline sync is the strongest case for KMP: the store schema, the outbox, the ordering rules, the backoff, the idempotency keys and the conflict strategy are pure logic that must behave **identically** on both platforms, and a divergence between an Android and an iOS implementation of the same queue produces data bugs that are almost impossible to reproduce. Put all of it in `commonMain`, and leave only scheduling and connectivity to the targets.
+
+## The boundary
+
+| Layer | Source set | Why |
+|---|---|---|
+| Store schema, DAOs, outbox table, drain algorithm, collapsing, backoff, conflict resolution | `commonMain` | One implementation, one test suite, no divergence |
+| HTTP client and serialization | `commonMain` (Ktor + kotlinx.serialization) | Same headers, same retry classification on both targets |
+| Connectivity observation | `expect`/`actual` or injected interface | `ConnectivityManager` vs `NWPathMonitor` |
+| Scheduling the drain | The host apps | `WorkManager` in `androidMain`/the Android app, `BGTaskScheduler` in the iOS app |
+| A secure place for credentials | `expect`/`actual` | Keystore vs Keychain — see [mobile-security](../../mobile-security/SKILL.md) |
+
+Prefer an injected interface over `expect`/`actual` for connectivity: it is easier to fake in `commonTest`, and it keeps the shared code free of platform conditionals.
+
+## The store and the outbox
+
+**SQLDelight** is the common choice: one `.sq` schema, generated typed queries, and `asFlow()` reactive reads on both targets.
+
+```sql
+-- outbox.sq
+CREATE TABLE outbox (
+  id              TEXT NOT NULL PRIMARY KEY,   -- operation UUID = idempotency key
+  entityType      TEXT NOT NULL,
+  entityId        TEXT NOT NULL,
+  operation       TEXT NOT NULL,
+  payload         TEXT NOT NULL,               -- changed fields only
+  attempts        INTEGER NOT NULL DEFAULT 0,
+  nextAttemptAt   INTEGER NOT NULL,
+  lastError       TEXT,
+  createdAt       INTEGER NOT NULL
+);
+
+dueInOrder:
+SELECT * FROM outbox WHERE nextAttemptAt <= :now ORDER BY createdAt ASC;
+```
+
+Drivers differ per target (`AndroidSqliteDriver`, `NativeSqliteDriver`, and an in-memory JDBC driver for JVM tests) but the queries and the transaction semantics do not. Room's KMP support is an alternative; check the version's target coverage before choosing it.
+
+Write the optimistic change and the outbox insert in one `transaction { }`.
+
+## The drain in commonMain
+
+```kotlin
+class SyncEngine(
+    private val outbox: OutboxDao,
+    private val api: SyncApi,
+    private val clock: Clock,                     // injected: never Clock.System inside the logic
+    private val scope: CoroutineScope,
+) {
+    private val mutex = Mutex()
+
+    suspend fun drain() = mutex.withLock {          // single-flight across reconnect bursts
+        for (entry in outbox.dueInOrder(clock.now())) {
+            when (val result = api.send(entry, idempotencyKey = entry.id)) {
+                is Sent      -> outbox.confirm(entry)                    // delete + mark synced, one transaction
+                is Permanent -> outbox.deadLetter(entry, result.reason)  // never blocks the queue
+                is Conflict  -> resolve(entry, result.serverVersion)
+                is Transient -> {
+                    outbox.scheduleRetry(entry, backoff(entry.attempts + 1))
+                    if (result.isOffline) break
+                }
+            }
+        }
+    }
+}
+```
+
+A `Mutex` is the right primitive here: the current Kotlin/Native memory manager allows shared mutable state across threads, so the same engine instance works on both targets without freezing rules.
+
+Do not read the clock inside the logic. Inject `Clock` so backoff and expiry are deterministic in `commonTest`, and because a device clock that is hours off must never decide ordering.
+
+## Ktor
+
+```kotlin
+HttpClient {
+    install(ContentNegotiation) { json() }
+    install(HttpRequestRetry) {
+        retryOnServerErrors(maxRetries = 2)
+        exponentialDelay()                        // in-session only; the durable schedule is the outbox
+    }
+    install(HttpTimeout) { requestTimeoutMillis = 30_000 }
+}
+```
+
+`HttpRequestRetry` covers a blip inside one drain. It does not survive process death, so the outbox's `nextAttemptAt` remains the real retry schedule. Send `Idempotency-Key` from the entry id on every mutating request and `If-Match` with the stored version on updates; classify `412` as `Conflict`, other 4xx as `Permanent`, 5xx/408/429 and IO failures as `Transient`.
+
+## Scheduling from the hosts
+
+Both hosts call the same shared `drain()`:
+
+- **Android:** a `CoroutineWorker` enqueued as unique work with a `CONNECTED` constraint and `BackoffPolicy.EXPONENTIAL`; return `Result.retry()` for transient outcomes. See [android.md](android.md).
+- **iOS:** `BGAppRefreshTaskRequest` / `BGProcessingTaskRequest` plus a drain on scene activation; always schedule the next request and call `setTaskCompleted(success:)`. See [ios.md](ios.md).
+- The suspend function is exposed to Swift as a completion-handler function; cancel it from the task's `expirationHandler` so an expired background task does not leave a half-drained queue holding the mutex.
+
+Platform limits are unchanged by KMP — [background.md](../../mobile-performance/references/background.md) applies in full.
+
+## Testing
+
+This is where the shared design pays for itself: every case in the skill's §9 is a `commonTest` against an in-memory driver and a fake `SyncApi`, and it runs on the JVM *and* on the Kotlin/Native iOS test binary, which is the only way to prove the two targets behave the same.
+
+- Fake `SyncApi` returning: success, success-after-the-response-was-lost, `Conflict` with a newer server version, `Permanent`, and `Transient`.
+- Injected `Clock` and `kotlinx-coroutines-test` for backoff timing.
+- Process-death is a host-level test; the shared part is covered by "reopen the database and drain again".
+- Run `commonTest` on both targets in CI. A test suite that only runs on JVM leaves the Kotlin/Native behaviour unverified, which defeats the reason for sharing the code.
+
+## Official documentation
+
+- Kotlin Multiplatform: https://kotlinlang.org/docs/multiplatform.html
+- SQLDelight: https://sqldelight.github.io/sqldelight/
+- Ktor client retry and timeouts: https://ktor.io/docs/client-retry.html
+- kotlinx.serialization: https://kotlinlang.org/docs/serialization.html
+- Kotlin/Native memory management: https://kotlinlang.org/docs/native-memory-manager.html

package/skills/mobile-offline-sync/references/react-native.md

@@ -0,0 +1,108 @@
+# Offline sync in React Native and Expo
+
+The JavaScript runtime is the weakest link here: it is torn down when the app is killed, and it gets little or no background time. So the durable part of the design — the store and the outbox — must be on disk, and the drain must be able to start from nothing on the next launch. An in-memory queue in a Redux store, or a promise chain waiting for the network, does not survive the swipe-up that ends the process.
+
+## The store
+
+| Option | Fits when |
+|---|---|
+| `expo-sqlite` or `op-sqlite` | You want SQL and full control; the usual base for a real outbox |
+| `WatermelonDB` | Large local datasets with a defined sync protocol (pull/push with a `last_pulled_at` checkpoint) |
+| `RxDB`, `PowerSync`, Legend-State, Firestore, Realm | The sync engine comes with the product — read its conflict rules instead of writing your own |
+| `react-native-mmkv` / `AsyncStorage` | Settings and small caches. Not a store for syncable records |
+
+TanStack Query is a cache, not a store: `persistQueryClient` plus `onlineManager` and paused mutations give you read-offline and replay-on-reconnect, which is enough for the "read cache" and simple "queued writes" levels in the skill's §2. It is not enough when the queue must survive process death with guaranteed ordering and per-entity collapsing — that needs rows in SQLite.
+
+## The outbox in SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS outbox (
+  id             TEXT PRIMARY KEY,    -- client UUID = idempotency key
+  entity_type    TEXT NOT NULL,
+  entity_id      TEXT NOT NULL,
+  operation      TEXT NOT NULL,       -- create | update | delete
+  payload        TEXT NOT NULL,       -- JSON of changed fields only
+  attempts       INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at INTEGER NOT NULL,
+  last_error     TEXT,
+  created_at     INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS outbox_ready ON outbox (next_attempt_at, created_at);
+```
+
+Insert the outbox row and apply the optimistic local change in one SQLite transaction. Generate the id with a UUID implementation that works in Hermes — `crypto.randomUUID` is not guaranteed in every runtime version, so `expo-crypto`, `react-native-uuid` or `react-native-get-random-values` + `uuid` is the safe route. Do not use `Math.random()` for an idempotency key.
+
+## Draining
+
+```ts
+let draining = false;
+
+export async function drain(): Promise<void> {
+  if (draining) return;                 // NetInfo fires in bursts on reconnect
+  draining = true;
+  try {
+    for (const entry of await dueEntriesInOrder()) {
+      try {
+        await api.send(entry, { idempotencyKey: entry.id });
+        await db.withTransactionAsync(async () => {
+          await deleteEntry(entry.id);
+          await markSynced(entry.entity_id);
+        });
+      } catch (error) {
+        if (isPermanent(error)) await deadLetter(entry.id, String(error));
+        else {
+          await scheduleRetry(entry.id, backoff(entry.attempts + 1));
+          if (isOffline(error)) break;
+        }
+      }
+    }
+  } finally {
+    draining = false;
+  }
+}
+```
+
+Triggers: `AppState` returning to `'active'`, a `NetInfo` event, an explicit pull-to-refresh, and a background task where one is available. Not `setInterval` — a JS timer does not run when the app is backgrounded, and when it does run it is the polling pattern the platform penalizes.
+
+## Connectivity
+
+`@react-native-community/netinfo` exposes `isConnected` (an interface is up) and `isInternetReachable` (a reachability probe, which may be `null` while unknown). Only the second approximates "the server can be reached", and neither is proof — a successful API call is. Use the event as a hint to call `drain()`.
+
+With TanStack Query, wire NetInfo into `onlineManager` so queries and mutations pause and resume with connectivity instead of failing:
+
+```ts
+onlineManager.setEventListener((setOnline) =>
+  NetInfo.addEventListener((state) => setOnline(Boolean(state.isConnected))),
+);
+```
+
+## Background
+
+JavaScript gets very little background time, and the rules are the platform's, not React Native's — see [background.md](../../mobile-performance/references/background.md).
+
+- **Expo:** `expo-task-manager` with the SDK's background task/fetch module. The module name and API have changed across SDK versions; check the docs for the pinned SDK rather than copying an older snippet.
+- **Bare React Native:** Headless JS on Android (started from a native service or a data push), and a community bridge to `BGTaskScheduler` on iOS.
+- Whatever runs in the background must boot its own dependencies: no navigation state, no hydrated store, no React context. Write the drain so it can be called with nothing but a database handle and an API client.
+- For file uploads that must finish after the app is suspended, use a library backed by the platform's background transfer rather than `fetch`.
+
+## Idempotency and conflicts
+
+- Send the entry id as `Idempotency-Key`; `fetch` and `axios` will not retry for you, but the platform layer and proxies can re-send, and the user will retry by hand.
+- `axios-retry` or an interceptor is fine for *transient* in-session retries, but the durable retry schedule must live in the outbox, because the interceptor dies with the process.
+- Send `If-Match` with the stored ETag on updates and treat `412` as the conflict signal, applying the per-entity strategy from the skill's §6. Send only changed fields; a full-object PUT turns every concurrent edit into a conflict.
+
+## Testing
+
+- Unit-test the outbox against an in-memory or temp-file SQLite database; ordering, collapsing, dead-lettering and transaction atomicity need no device.
+- Fake the API module (`jest.mock`) or use MSW to express the cases that matter: a response lost after the server committed, and a `412` conflict. Mocking `fetch` at the global level is enough for both.
+- Use fake timers for backoff, and inject the clock rather than calling `Date.now()` inside the retry logic.
+- End-to-end: Detox and Maestro can toggle device connectivity around a scripted flow; combine with `adb shell am kill` or Detox's `device.terminateApp()` to cover process death mid-drain.
+
+## Official documentation
+
+- Expo SQLite: https://docs.expo.dev/versions/latest/sdk/sqlite/
+- Expo TaskManager: https://docs.expo.dev/versions/latest/sdk/task-manager/
+- NetInfo: https://github.com/react-native-netinfo/react-native-netinfo
+- React Native AppState: https://reactnative.dev/docs/appstate
+- TanStack Query offline support: https://tanstack.com/query/latest/docs/framework/react/guides/network-mode
+- WatermelonDB sync: https://watermelondb.dev/docs/Sync/Intro

package/skills/mobile-performance/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: mobile-performance
+description: Diagnoses and prevents mobile performance regressions on every stack — Flutter, native Android, native iOS, React Native and Kotlin Multiplatform. Covers startup time, rendering and jank, memory, battery and background work, app size, the profiler and benchmark to use on each platform, and regression detection in CI. Use when an app is slow, janky, heavy or draining the battery, when setting performance budgets, or when a release must not regress.
+intents: [performance]
+stacks: ["*"]
+---
+
+# Mobile Performance
+
+One performance process for every mobile stack. This file holds the method and the budgets; each platform's profilers, benchmark harnesses and fixes live in its reference.
+
+## 1. Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) |
+| Native Android: Jetpack Compose or Views | [references/android.md](references/android.md) |
+| Native iOS: SwiftUI or UIKit | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform, shared code and hosts | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| Battery drain, background jobs, wake locks, scheduled sync | [references/background.md](references/background.md) |
+
+In Flutter, React Native and KMP apps, the native reference applies to the host side of the problem: the Android or iOS process still owns startup, frame delivery and battery accounting.
+
+## 2. Never optimize before you measure
+
+A performance task that starts with a code change is a guess. Produce these four things, in order, before touching anything:
+
+1. **A journey.** "Cold start to the feed", "scrolling the order list", "typing in the search field". Not "the app is slow".
+2. **A number and a device.** The current value, the device model, the OS version, and the build type. A debug build proves nothing: Flutter and React Native run unoptimized in debug, and Android/iOS debug builds disable compiler optimizations. Measure in profile or release.
+3. **A budget.** The value that makes the journey acceptable (see §3).
+4. **A repeatable measurement.** The exact command, trace or benchmark that produced the number, so the fix can be proven and the regression can be caught later.
+
+If the request arrives without a measurement, say so and give the command that produces one for this stack before proposing fixes. Reporting "I optimized X" without a before and after number is not a result.
+
+## 3. The budgets
+
+**Startup.** Distinguish the three: *cold* (process created), *warm* (process alive, activity/scene recreated) and *hot* (resume). Cold start is the one users judge. Measure to first frame and to the first frame the user can actually use — these differ whenever the first frame is a skeleton or spinner.
+
+| Signal | Usable budget |
+|---|---|
+| Cold start to first frame | under ~1.5 s on a mid-range device; Android vitals flags 5 s as excessive for cold start |
+| Cold start to interactive content | under ~2.5 s, with a meaningful placeholder before it |
+| Warm start | under ~1 s |
+
+**Rendering.** The budget is one frame period: about 16.7 ms at 60 Hz, about 8.3 ms at 120 Hz. Two numbers matter, and an average hides both:
+
+- **p90/p99 frame time** — the slow frames are the ones the user sees.
+- **Frozen frames** — anything over ~700 ms of unresponsiveness reads as a freeze; Android vitals counts frames over 700 ms as frozen, and Apple counts a main thread blocked beyond ~250 ms as a hang.
+
+Never report "average frame time is fine". Report the percentile and the count of dropped frames over the journey.
+
+**Memory.** Track the steady-state footprint after the journey has run several times, not the peak during one load. The failure modes are: growth that never comes back down (a leak), a peak that gets the process killed on low-memory devices, and bitmap/image decoding at a size far larger than the view. Compare the same journey repeated three times: flat is healthy, monotonically rising is a leak.
+
+**Battery and network.** Energy is not measured in the app's UI; it is measured in wakeups, wake locks, jobs, and bytes transferred while the screen is off. Anything periodic — polling, a foreground service kept alive, location updates, an unbatched analytics flush — is the first suspect. See [references/background.md](references/background.md).
+
+**App size.** Download size, not the size of the build directory. Size is a conversion and update-adoption problem, and on Android it is also a Play Console limit. Every stack ships a size analyzer; the reference names it.
+
+## 4. Find the cause, not a symptom
+
+Rendering problems come from one of four places. Identify which before proposing a fix:
+
+1. **Too much work per frame on the UI thread** — layout of a deep tree, a synchronous decode, JSON parsing, a database read, a `List`/`ListView` that builds all children.
+2. **Too many updates** — a state container that emits on every keystroke, a widget/composable/component that rebuilds because its input is not stable, an animation driven from the JS or UI thread instead of the compositor.
+3. **Expensive painting** — overdraw, shadows and blurs over large areas, clipping with antialiasing and saved layers, oversized images.
+4. **Blocking the main thread from elsewhere** — an await that resolves on the main queue, a lock, a plugin/native module call that is synchronous, a file or network call that should be off-thread.
+
+Startup problems are usually: work done eagerly in the application/AppDelegate entry point that could be deferred, dependency-injection graphs built at launch, a synchronous read of preferences or a database, third-party SDKs initialized before first frame, and — on Android — missing Baseline Profiles so hot code runs interpreted.
+
+## 5. Detect the regression before the user does
+
+A performance fix that is not guarded comes back. Every stack has a benchmark harness that produces a number in CI; the reference names it. Set it up so that:
+
+- The benchmark runs on a fixed device or emulator/simulator model, in release or profile mode, with the app warmed the same way each run.
+- The result is compared against a stored baseline, and the build fails (or flags) past a threshold — an absolute budget for startup and frame time, and a percentage delta for size.
+- Percentiles, not averages, are compared, and the run count is high enough that the noise band is known. Report the noise band with the threshold; a 5% threshold on a benchmark with 15% variance only produces false alarms.
+- Field data backs the lab data: Android vitals and Play Console, Xcode Organizer and MetricKit, or the app's own tracing. Lab benchmarks catch a regression before release; field metrics tell you whether it mattered. See [mobile-observability](../mobile-observability/SKILL.md) for wiring these signals into production.
+
+## 6. Evidence and severity
+
+Point to `file:line` for every finding, name the measurement that proves it, and give the fix in the platform's own API.
+
+- **Critical:** the journey is unusable or the process dies — ANR or a hang over a few seconds, an out-of-memory kill, a cold start past 5 s, a leak that grows until the app is terminated.
+- **High:** the user perceives it every time — visible jank on the main scroll, cold start over budget, battery drain flagged by the platform, an app size jump that breaks a store limit.
+- **Medium:** measurable but intermittent — occasional dropped frames, a redundant rebuild, a cache miss that costs a network round trip.
+- **Low:** headroom — work that could be deferred or batched without a current user-visible cost.
+
+Say which findings came from reading code only. Code review can prove an unbounded list build or a main-thread file read; it cannot prove frame time, memory growth or energy use. Those need the profiler run named in the reference.