# ADR 0042: Sync held back on mobile data

- **Status:** decided 10 Nov 2026 by the developer: D1 is their own request, D2 to D5
  the agent's recommendations, which they chose. Not built yet.
- **Builds on:** ADR 0014 (halkyon_app, every app's shell, with its `SyncService`).

## Context

Every Halkyon app syncs whenever something changes and on a timer, on whatever network
the device has. Learn's library holds tens of thousands of rows and hundreds of
megabytes of PDFs; a first sync, or an import on another device, can take a phone's
monthly data on the go. The developer asked (10 Nov 2026): *"It should hold back
everything, asking the user whether one wants to sync. Then, give also the option to
exclude files, images etc."*

## Decisions

- **D1.** On mobile data, every app holds back its sync, rows and files alike, and asks
  first. Built once, in halkyon_app, around its `SyncService`; nothing an app does on
  the device waits on it (local-first as before: what is written is kept and sent
  later).
- **D2.** *Mobile data* is a **metered** connection as the operating system says: on
  Android its `NET_CAPABILITY_NOT_METERED` missing, which takes in cellular and also a
  phone's hotspot or a Wi-Fi network marked metered; read by a few lines of Kotlin in
  halkyon_app's plugin code (`connectivity_plus` tells only the kind of network, which
  misses the hotspot). iOS: `NWPath.isExpensive`, once the iOS builds ship. Desktops
  are never metered.
- **D3.** It asks with a **quiet banner** above the lists, never a dialog: *On mobile
  data · 12 changes waiting* with *Sync now*, *Without files* and *Not now*. *Not now*
  hides it until something new waits. Pulling a list down to sync is an explicit ask
  too, and syncs as *Sync now* would.
- **D4.** An answer **holds until the connection changes**: while the device stays on
  this metered network; asked again after Wi-Fi came and went, or when the app starts
  again on mobile data.
- **D5.** Settings › Sync has *On mobile data*: **Ask** (the default), **Without files**,
  **Everything**. No *Never*: *Not now* holds back already. A device setting (as the
  look), not synced: a tablet on Wi-Fi alone and a phone differ.

## What "without files" means

Rows sync; files neither go up nor come down. Each app names its files to halkyon_app
as a queue of its own (Learn's asset uploads and downloads, its PDFs and Jellyfin
covers; Todo's attachments, ADR 0043; Train's maps' tiles stay as they are, fetched
when shown), which `SyncService` pauses and resumes. What is waiting shows in Sync's
card (*3 files waiting for Wi-Fi*).

## To work out when building

- Where the banner sits in each app's frame: halkyon_ui's `NavigationFrame` has no
  place for one above every tab yet.
- The sync engine's stream: whether held back means not opening it at all (the
  recommendation: nothing goes over the network, not even the handshake) or opening it
  and sending nothing.
- Learn's offline reads (b578fcb9) must not wait on a sync held back: the tests of
  `ContentKeys` and the gateways already run without one.