reis-mobile 0.7.2 → 0.8.0

package/skills/mobile-observability/references/kotlin-multiplatform.md

@@ -0,0 +1,76 @@
+# Observability in Kotlin Multiplatform
+
+Two things are shared and one is not. The **instrumentation** — what you record, the event names, the attributes, the sampling decision, the redaction rules — belongs in `commonMain`, so both apps report the same names and a dashboard can compare them. The **reporting SDK** is per host: Crashlytics/Sentry on Android through the Android SDK, the same vendor on iOS through its Apple SDK. There is no cross-platform crash reporter that covers Kotlin/Native crashes as well as each platform's native reporter does.
+
+## The boundary
+
+```kotlin
+// commonMain — the only API the shared code knows about
+interface Telemetry {
+    fun breadcrumb(name: String, attributes: Map<String, String> = emptyMap())
+    fun setKey(key: String, value: String)
+    fun recordError(throwable: Throwable, fatal: Boolean = false)
+    fun startSpan(name: String): Span
+}
+```
+
+`androidMain` implements it over the Android SDK; `iosMain` implements it over the Apple SDK, or the iOS app injects a Swift implementation through the interface. Prefer injection from the host over `expect`/`actual` here: it keeps the vendor out of the shared dependency graph and makes `commonTest` a matter of passing a recording fake.
+
+Everything else — which events exist, their attribute keys, the sampling rate, the redaction — lives in `commonMain` and is tested once.
+
+## Kotlin/Native crashes on iOS
+
+This is the part that surprises teams:
+
+- An **unhandled Kotlin exception on iOS terminates the process**. By default it is reported as a native crash, and the report's usefulness depends entirely on the framework's dSYM being uploaded alongside the app's.
+- `setUnhandledExceptionHook` lets you record the Kotlin exception through the host reporter *before* the process dies — use it to attach the shared-layer context (the screen, the operation, the outbox depth) that a raw native crash report will not carry. Do not use it to swallow the exception.
+- Kotlin frames appear as addresses unless the framework is built with debug symbols and those symbols are uploaded. Check `binaryOptions` and the framework build configuration, and verify once with a deliberate release crash from shared code.
+- `kotlin.native.binary.` options that strip symbols will make every shared-code crash unreadable. Confirm what the release framework actually ships.
+
+On Android the shared code is ordinary JVM code: Kotlin exceptions reach the default uncaught handler and the reporter sees them normally, symbolicated through the R8 mapping file.
+
+## Instrumenting the shared layer
+
+- **Ktor:** a client plugin is the single place to generate the request id, add the header, record the span and drop a network breadcrumb — for both platforms at once.
+
+```kotlin
+val client = HttpClient {
+    install(createClientPlugin("Observability") {
+        onRequest { request, _ ->
+            request.headers.append("X-Request-Id", uuid4().toString())
+        }
+        onResponse { response ->
+            telemetry.breadcrumb("network", mapOf(
+                "host" to response.request.url.host,          // host only, never the full URL
+                "status" to response.status.value.toString(),
+            ))
+        }
+    })
+}
+```
+
+- **Repository and sync errors:** the shared sync engine ([mobile-offline-sync](../../mobile-offline-sync/SKILL.md)) is where the most valuable context lives — outbox depth, attempt counts, conflict outcomes. Record it as keys and breadcrumbs from `commonMain` so both apps report it identically.
+- **Coroutine failures:** an exception in a shared `CoroutineScope` with no handler is lost. Install a `CoroutineExceptionHandler` that routes to `Telemetry.recordError`, and remember that a failing child in a plain `Job` cancels the scope — the report must say which.
+- **Spans:** `OSSignposter` on iOS and trace sections on Android are host concerns; expose `startSpan` and let each `actual` map it, so the same span name shows up in Instruments and in a system trace.
+
+## Segmentation
+
+The dimensions in the skill's §4 apply, plus one KMP-specific pair worth setting as keys: the **shared module version** (if it is versioned independently of the apps) and the **target**. "Only on iOS" is the single most useful filter in a KMP dashboard, and it only exists if the target is an attribute on every signal.
+
+## Platform field data
+
+Android vitals, Play Console ANRs, Xcode Organizer and MetricKit all apply unchanged — the shared code runs inside two ordinary apps. See [android.md](android.md) and [ios.md](ios.md). The lab counterpart, including how to tell shared cost from host cost, is [mobile-performance/references/kotlin-multiplatform.md](../../mobile-performance/references/kotlin-multiplatform.md).
+
+## Testing
+
+- A recording fake `Telemetry` in `commonTest` asserts that a failing sync drain records the error once, with the expected keys, and does not log the payload.
+- The redaction rules are shared code: test them against a payload containing a token, on both JVM and Native test targets.
+- Sampling decisions should be deterministic given an injected seed or clock, so the test can assert "a failed session is always kept".
+
+## Official documentation
+
+- Kotlin Multiplatform: https://kotlinlang.org/docs/multiplatform.html
+- Kotlin/Native and Swift/Objective-C interop: https://kotlinlang.org/docs/native-objc-interop.html
+- Ktor client plugins: https://ktor.io/docs/client-custom-plugins.html
+- Crashlytics: https://firebase.google.com/docs/crashlytics
+- MetricKit: https://developer.apple.com/documentation/metrickit

package/skills/mobile-observability/references/react-native.md

@@ -0,0 +1,62 @@
+# Observability in React Native and Expo
+
+A React Native app fails in two runtimes. A **JavaScript error** produces a red screen in development and, in production, either a caught error boundary or a fatal that the native crash reporter never sees on its own. A **native crash** produces a normal Android/iOS crash with no JavaScript stack. A setup that covers only one of them explains half the incidents — and the half it misses is usually the harder one.
+
+## Cover both runtimes
+
+Use a reporter with a React Native SDK (`@sentry/react-native`, Bugsnag, Crashlytics via `@react-native-firebase/crashlytics`, Embrace). What to check in the configuration:
+
+- **JavaScript fatals are reported as fatals**, not swallowed by a global handler that logs and continues. `ErrorUtils.setGlobalHandler` is the underlying mechanism; the SDK wraps it, and an app that installs its own handler afterwards silently disables reporting.
+- **Unhandled promise rejections** are captured. In Hermes they do not reach the global error handler by default, and an SDK option or a rejection tracker is needed.
+- **Native crashes** are captured by the SDK's Android and iOS layers — which means the native install steps (autolinking plus any Gradle/Podfile lines the SDK documents) must actually be present. Verify on a release build, not in Metro.
+- **React error boundaries** report and then render a fallback. A boundary that catches and shows a blank screen without reporting is the most common invisible failure in RN apps.
+
+## Source maps are the whole game
+
+A production JavaScript stack trace is minified Hermes bytecode offsets. Without source maps uploaded per build, every report is unreadable:
+
+```bash
+# The release build emits the bundle and its map; upload both, per platform, per version.
+npx react-native bundle --platform android --dev false \
+  --entry-file index.js \
+  --bundle-output android/app/build/generated/.../index.android.bundle \
+  --sourcemap-output index.android.bundle.map
+```
+
+- The SDK's Gradle plugin / Xcode build phase usually automates the upload; confirm it ran for the shipped variant, and that the **release identifier** (version + build number + bundle hash) matches what the app reports at runtime. A mismatched release is the usual reason a correctly uploaded map still does not symbolicate.
+- **Expo:** `eas build` uploads source maps when the SDK's config plugin is installed; **`eas update` publishes a new bundle without a new build**, so each OTA update needs its own source map upload and its own release identifier. An OTA-heavy app with build-time-only uploads has unreadable traces for every update after the first.
+- Android also needs the R8 mapping file and iOS the dSYMs for native frames. Three artifacts, as in every cross-platform stack.
+
+## OTA updates change what "app version" means
+
+With `expo-updates` or CodePush, the native build and the JavaScript bundle version independently. Every signal must carry **both** — the native version/build and the update/bundle id — or you cannot tell which JavaScript is actually running on a device reporting a crash. Set the update id as a custom key at startup and include it in the release identifier used for source maps.
+
+This is the single most important RN-specific item in the skill's §4 segmentation list.
+
+## Context and breadcrumbs
+
+- **Navigation:** React Navigation's `onStateChange`, or Expo Router's equivalent, produces a screen breadcrumb per transition. Most SDKs ship an integration that does it for you.
+- **Network:** wrap `fetch`/`axios` once to generate the request id, add the `X-Request-Id` header, and record method, host, status and duration. SDK network breadcrumbs are on by default in some vendors and capture full URLs — review and restrict that before shipping, since query strings carry tokens.
+- **Custom keys:** screen, auth state, flag values, update id, connectivity class from NetInfo, outbox depth.
+- **Redux/Zustand/TanStack Query:** an action or query-error middleware that forwards failures with the state slice that caused them. Beware the vendor Redux integrations that attach the **entire state tree** to every event — that is both a cost and a privacy problem.
+
+## Performance and native field data
+
+- The RN SDKs report app-start, slow/frozen frames and, in newer versions, some JS-thread metrics. Treat them as indicators and read the platform's own data as the truth.
+- Android vitals and Play Console ANR data, Xcode Organizer and MetricKit all still apply and still see the real process — see [android.md](android.md) and [ios.md](ios.md). An ANR in a React Native app is an Android ANR, reported by Play, and invisible from JavaScript.
+- The lab counterparts are in [mobile-performance/references/react-native.md](../../mobile-performance/references/react-native.md).
+
+## Privacy and consent
+
+- The Play Data safety form and the iOS privacy nutrition label plus `PrivacyInfo.xcprivacy` must cover the native SDKs the JS packages pull in. Expo config plugins add native SDKs you never wrote a line against.
+- Gate initialization on consent; most SDKs support initializing with sending disabled and enabling it later.
+- Implement `beforeSend` (or the vendor's equivalent) to strip tokens, bodies and query strings, and unit-test it — it is plain JavaScript, so this is a cheap test with real value.
+- `console.log` left in production ships strings into the device log and, with some SDK configurations, into breadcrumbs. Strip logs in release (`babel-plugin-transform-remove-console` or equivalent) or make the logger deliberate.
+
+## Official documentation
+
+- React Native source maps and symbolication: https://reactnative.dev/docs/symbolication
+- Expo EAS Update: https://docs.expo.dev/eas-update/introduction/
+- React Native Firebase Crashlytics: https://rnfirebase.io/crashlytics/usage
+- Sentry for React Native: https://docs.sentry.io/platforms/react-native/
+- NetInfo: https://github.com/react-native-netinfo/react-native-netinfo

package/skills/mobile-offline-sync/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: mobile-offline-sync
+description: Designs and reviews offline-first mobile data on every stack — Flutter, native Android, native iOS, React Native and Kotlin Multiplatform. Covers the local store, the outbox of pending mutations, idempotency keys, retry and backoff, conflict resolution, reconnection, and how to test a flaky network deterministically. Use when an app must work without connectivity, when writes are lost or duplicated after reconnecting, or when local and server data disagree.
+intents: [offline]
+stacks: ["*"]
+---
+
+# Mobile Offline Sync
+
+One design for offline-capable mobile data, on every stack. This file holds the model and the failure cases; each platform's storage engines, queue runners and network-condition tooling live in its reference.
+
+## 1. Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) |
+| Native Android | [references/android.md](references/android.md) |
+| Native iOS | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+
+Background scheduling — when the sync is actually allowed to run — is in [mobile-performance/references/background.md](../mobile-performance/references/background.md). Where the queue and the store belong in the app's layers is in [mobile-architecture](../mobile-architecture/SKILL.md).
+
+## 2. Decide what "offline" means here, first
+
+Most offline bugs come from building more than the product needs, or less. Pick one of these three before designing anything:
+
+| Level | The app can… | Cost |
+|---|---|---|
+| **Read cache** | Show previously fetched data while offline; writes fail with a clear message | Low. A store and a freshness policy |
+| **Queued writes** | Accept writes offline, apply them optimistically, send them on reconnect | Medium. Everything in §3–§6 |
+| **Full replication** | Work indefinitely offline, with concurrent edits on several devices merged | High. Needs a server designed for it: versioning, per-record change history, or a CRDT/sync engine |
+
+Level 2 is what most apps need and what this skill is written for. Do not build level 3 machinery for a product whose users are offline for minutes; do not sell level 1 as "works offline" when users expect their edits to survive.
+
+## 3. The local store is the source of truth for the UI
+
+Offline-first inverts the usual flow. The UI never reads from the network; it reads from the local store, and the network's only job is to fill and drain that store.
+
+```
+UI  ──reads──▶  local store  ◀──writes──  sync engine  ◀──▶  server
+        ▲                ▲
+        └──writes────────┘  (optimistic, immediately visible)
+```
+
+What this requires:
+
+- **A real database, not a cache of responses.** Rows with your own primary keys, queryable, with a schema you migrate. Caching JSON blobs keyed by URL cannot answer "show me this user's unsent orders".
+- **Reactive reads.** The store emits on change (Flow, Stream, publisher, subscription) so an applied mutation or a completed sync updates every screen without a manual refresh.
+- **Per-record sync state**, stored next to the record: `synced`, `pending`, `failed`, plus the server version/ETag it was last based on and the time it was fetched. Without it the UI cannot show "sending…" and the engine cannot tell a local edit from a server row.
+- **A freshness policy.** How stale is too stale, per entity. A price list and a chat message do not have the same answer, and "refresh everything on launch" is what makes launches slow.
+
+## 4. The outbox: every write is a durable, replayable intent
+
+A mutation made offline is not a paused HTTP call. It is a record in a table.
+
+An outbox entry carries: a **stable client-generated id** (UUID, created on the device), the **operation** and its payload, the **entity it targets**, the **attempt count**, the **next attempt time**, the **last error**, and the **creation time**.
+
+Consequences that are easy to get wrong:
+
+- **Generate ids on the client.** A record created offline needs an id immediately, because the UI shows it and later operations reference it. Use a UUID (or ULID, which sorts by time) as the real primary key and let the server accept it, rather than mapping a temporary id to a server id afterwards. If the server must assign the id, you need an explicit id-mapping table and every queued operation that references the new record must be rewritten when the id arrives — design for that deliberately or avoid it.
+- **Order matters, per entity.** Create-then-update-then-delete on the same record must reach the server in that order. Process the queue in order per entity key; parallelize across unrelated entities only.
+- **Collapse redundant operations before sending.** Three edits to the same field while offline are one PUT. A create followed by a delete of a record the server never saw is *nothing at all* — both entries are dropped. Doing this at drain time, not at enqueue time, keeps the UI history honest.
+- **A failed entry must not block the queue forever.** After N attempts, move it to a dead-letter state, surface it to the user, and continue with the rest. A permanent 400 retried forever stops every later write.
+- **The queue survives everything.** Process death, reboot, app update, low storage. That means a database table, not an in-memory list, and a migration story for the payload format when the app updates while entries are pending.
+
+## 5. Idempotency: the network will lie to you
+
+The dangerous failure is not "the request failed". It is "the request succeeded and the response was lost" — the device retries, and the user has two orders.
+
+- **Send an idempotency key with every mutating request.** The client-generated operation id is that key; put it in a header (`Idempotency-Key` is the common spelling) or in the body. The server stores the key with the result and returns the *original* result for a repeat, instead of performing the operation again.
+- **Without server support, retrying a POST is unsafe.** If the API has no idempotency mechanism, say so explicitly in the review: the choice is to add one server-side, to make the endpoint naturally idempotent (a PUT to a client-chosen id), or to accept duplicates. There is no client-only fix — a client that "checks whether it already exists" before retrying still races.
+- **Only delete the outbox entry after a confirmed success.** Acknowledge, then delete, in that order; a crash between the two costs a retry, which idempotency makes harmless. The reverse order costs a lost write.
+- **Deletes and increments need the same care.** `DELETE` is naturally idempotent for a given id; a relative operation ("add 1 to the counter") is not, and must be sent as an absolute value or carry a key.
+
+## 6. Conflict resolution: name the strategy, per entity
+
+A conflict is a server-side change to a record the device edited based on an older version. Detecting one requires a version: an ETag, a `version` integer, or an `updated_at` the server controls. **If the API returns no version, conflicts cannot be detected at all** — the last writer silently wins, and that must be stated as a finding rather than assumed to be the design.
+
+| Strategy | Use when | Cost |
+|---|---|---|
+| **Server wins** | Reference data the user does not edit — catalogues, settings pushed by an admin | None; discard the local change |
+| **Client wins (last write wins)** | Single-user data edited on one device at a time — a draft, a local preference | Silent data loss if the assumption breaks |
+| **Field-level merge** | Records where different fields change independently — a profile, a form | Needs per-field dirty tracking in the outbox, not a whole-object PUT |
+| **Ask the user** | The conflict is meaningful and rare — a document, an appointment | UI work, and a place to hold both versions until it is resolved |
+| **Append-only / event log** | Values that accumulate rather than replace — comments, measurements, a ledger | Changes the data model; removes most conflicts by construction |
+| **CRDT / sync engine** | Genuine multi-device concurrent editing | A library and a compatible backend; do not hand-roll it |
+
+Two rules regardless of strategy: **send only the fields that changed** (a full-object PUT turns every concurrent edit into a conflict), and **never resolve a conflict by silently discarding user input** — if the local version loses, the user is told, or the version is kept somewhere recoverable.
+
+## 7. Reconnection
+
+- **Connectivity APIs report the interface, not reachability.** "Connected to Wi-Fi" is true on a captive portal, behind a dead VPN, and on a hotel network that resolves DNS to a login page. Treat the connectivity event as a *hint to try*, and treat a successful request as the only proof of connectivity.
+- **Backoff with jitter.** Exponential, capped (a minute or two), with randomization. Without jitter, every device that lost the same backend retries in lockstep and re-creates the outage.
+- **Distinguish the error classes.** Retry on timeouts, 5xx, and connection failures. Do not retry a 4xx other than 408/429 — it will fail identically forever. Honour `Retry-After` on 429 and 503.
+- **Drain on the right triggers:** app foreground, connectivity regained, a periodic constrained background job, and an explicit user pull-to-refresh. Not a polling timer.
+- **Single-flight the drain.** Two concurrent drains after a fast reconnect/disconnect/reconnect send everything twice; a mutex or a single worker with unique work policy prevents it.
+
+## 8. Tell the user the truth
+
+Offline UX fails in predictable ways, and each one is reviewable:
+
+- [ ] The user can tell the difference between "saved on this device" and "saved on the server". A pending indicator per item, not one global banner.
+- [ ] An optimistic update that later fails is **rolled back visibly**, with the reason and a retry — never silently reverted, never left looking saved.
+- [ ] Stale data shows its age ("updated 2 hours ago") where staleness matters.
+- [ ] Actions that genuinely cannot work offline are disabled with an explanation, not offered and then failed.
+- [ ] Dead-lettered operations are reachable and retryable or discardable by the user; nothing is lost in silence.
+- [ ] Logging out, or clearing data, with a non-empty outbox asks the user first.
+
+## 9. Test the failure cases, not the happy path
+
+An offline feature that was only tested by toggling airplane mode is untested. The cases that break real implementations:
+
+1. Write offline → kill the process → relaunch → reconnect. The write must still be sent.
+2. Write → the response is lost after the server committed → retry. Exactly one record must exist.
+3. Two writes to the same record offline → reconnect. The server must end up with the final state, in order.
+4. Write offline → the same record is changed on the server → reconnect. The configured conflict strategy must be what actually happens.
+5. Reconnect with a large queue → the app is backgrounded mid-drain. The drain resumes and does not duplicate.
+6. A permanently rejected operation (validation error). The queue continues; the user is told.
+7. Clock skew: the device's clock is hours off. Nothing that decides ordering or expiry may depend on the device clock.
+8. App update with pending entries whose payload format changed.
+
+Each reference names the platform's tools for forcing these conditions — network link conditioners, emulator network profiles, and the fake/test doubles that make cases 2 and 4 deterministic instead of a race. Test-harness patterns are in [mobile-test](../mobile-test/SKILL.md).
+
+## 10. Evidence and severity
+
+Point to `file:line`, and name which of the nine cases in §9 the code fails.
+
+- **Critical:** data loss or duplication — writes dropped on process death, retries without idempotency, a conflict strategy that discards user input silently, an outbox held in memory.
+- **High:** the feature does not work as promised — the queue blocked by one failed entry, no backoff (battery and a self-inflicted outage), no conflict detection where concurrent edits are expected, optimistic updates never rolled back.
+- **Medium:** friction and waste — no operation collapsing, refetching everything on every launch, a connectivity check trusted as reachability.
+- **Low:** polish — missing per-item pending state, no age on stale data.

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