aw-sync: return and persist a SyncReport — a pass is a side effect, so nothing can report what it did

[ErikBjare]

A sync pass is modelled as a side effect rather than as a function that returns what it did. That single choice is why sync failures are structurally invisible, and it is cheap to reverse.

Today

• sync_run(...) -> Result<(), Box<dyn Error>> — success carries no information.

• The JNI wrapper reports a fixed string regardless of what happened:

  pull_all(&client).map_err(|e| format!("Sync pull failed: {}", e))?;
  Ok(json!({
      "success": true,
      "message": "Successfully pulled from all hosts"
  }).to_string())

  Ten peers or zero peers, a million events or none — identical output.

• Android persists exactly SyncStatus(completedAt: Long, success: Boolean) (Sync status is a timestamp and a boolean — the model cannot answer what synced, when next, or from whom aw-android#274).

• The daemon has no status at all; its only signal is exiting (aw-sync: per-peer and per-bucket errors abort the whole sync pass (and burn the supervisor's restart budget) #688).

The information mostly already exists and is discarded. sync_one computes new_events_count per bucket and logs it; sync_run knows which peers it found. None of it survives the call.

This is the mechanism behind #682: a daemon ran 102 consecutive passes importing nothing, logging Pulling... each time. Not that nobody looked — there was nothing to look at.

Proposal

Return a SyncReport from sync_run, aggregate it in pull_all/push, and persist the latest one:

pub struct SyncReport {
    pub started: DateTime<Utc>,
    pub finished: DateTime<Utc>,
    pub mode: SyncMode,
    pub peers: Vec<PeerReport>,   // one per peer considered
    pub pushed: Vec<BucketReport>,
}

pub struct PeerReport {
    pub device_id: String,
    pub hostname: String,
    pub path: PathBuf,
    pub outcome: PeerOutcome,     // Imported | Skipped(reason) | Failed(error)
    pub buckets: Vec<BucketReport>,
}

pub struct BucketReport {
    pub bucket_id: String,
    pub events_new: i64,
    pub resumed_at: Option<DateTime<Utc>>,
}

Then:

• aw-sync status (feat(aw-sync): add status doctor command and fail-loud empty-pull warnings #687) reports the last pass as well as current folder state.
• The JNI layer returns real counts, so Sync status is a timestamp and a boolean — the model cannot answer what synced, when next, or from whom aw-android#274 becomes a rendering job rather than a redesign.
• The daemon can persist last-pass status to a file, so aw-qt/aw-tauri can show "sync is running but two peers are failing" without the module having to die to be heard (aw-sync: per-peer and per-bucket errors abort the whole sync pass (and burn the supervisor's restart budget) #688).
• PeerOutcome::Skipped gives the duplicate-device_id dedupe from fix(aw-sync): skip duplicate device_id folders that truncate history on pull #686 somewhere to report itself, instead of a log line nobody reads.

Scope boundary

This covers facts about what a pass did. It deliberately does not cover facts the sync folder cannot currently express — "which device is this peer", "when did it last push", "is a peer missing that used to be here". Those need per-device metadata in the folder (the manifest discussed in ActivityWatch/activitywatch#302 / #691) and are out of scope here.

Worth doing first precisely because it is small, has no format implications, and unblocks three other issues.

Credit: found in a design review of aw-sync.

Related: #684, #687, #688, #682, ActivityWatch/aw-android#274.

cc @TimeToBuildBob

[TimeToBuildBob]

Implemented in #699.

sync_run / pull_all / push now return a SyncReport. The latest one is persisted under {data_dir}/aw-sync/last-sync-report.json (not the Syncthing folder). aw-sync status prints it; JNI returns real counts instead of a fixed success string; duplicate-device_id skips show up as PeerOutcome::Skipped.

Did not change error policy — a per-peer failure still aborts the pass (#688). The partial report is persisted on that path so the failure is visible afterwards.

[TimeToBuildBob]

Already implemented in #699 (zero-peer report test included).

#700 just landed, so that PR is DIRTY against master. Holding the rebase until #678 and #697 are in — one rebase over the remaining v0.14.0 sequence, not per-PR. Nothing further on this issue until then.

[TimeToBuildBob]

Closing the loop from the merged side — #699 landed as 37aa0b0 (2026-09-17T08:41:16Z) and this issue was closed by Erik one second later.

Verified against the acceptance criteria on master:

• sync_run / pull_all / push return a SyncReport, aggregated per pass — aw-sync/src/report.rs (PeerReport, PeerOutcome::Skipped { reason }, BucketReport, events_new/events_pulled/events_pushed counters).
• The latest report is persisted to {data_dir}/aw-sync/last-sync-report.json (atomic rename, unique temp name so overlapping daemon/Android writers can't truncate each other). Persist failure warns instead of failing an already-successful pass.
• aw-sync status prints the last pass — aw-sync/src/status.rs calls load_last_report(), and an unpersisted state reads as Last pass: (none — no pass has been persisted yet) rather than silence.
• The JNI fixed string is gone; to_jni_json() returns real counts, so Sync status is a timestamp and a boolean — the model cannot answer what synced, when next, or from whom aw-android#274 is a rendering job now.
• Master CI is green on the merge commit (success, run 2026-09-17T08:41:18Z).

Deliberately unchanged, per the scope note in the issue: error policy. A per-peer failure still aborts the pass — that partial report is now persisted on the abort path so the failure stays visible afterwards. The abort behaviour itself remains tracked at #688 (in-flight slice: #703).