A whole lot of stuff

lib/services/cloud_sync_service.dart

@@ -12,15 +12,30 @@ class SyncResult {
   final bool ranSync;
   final Object? error;
 
+  /// True when pull/merge completed but [CloudSyncService.syncNow]'s
+  /// `beforeUpload` gate (the app's ad-watch requirement — see
+  /// [AdService.showGateAd]) came back closed, so nothing local was
+  /// uploaded. Remote changes, if any, were still merged in.
+  final bool adGateBlocked;
+
   SyncResult.skipped()
       : ranSync = false,
-        error = null;
+        error = null,
+        adGateBlocked = false;
 
   SyncResult.success()
       : ranSync = true,
-        error = null;
+        error = null,
+        adGateBlocked = false;
 
-  SyncResult.failure(this.error) : ranSync = false;
+  SyncResult.failure(this.error)
+      : ranSync = false,
+        adGateBlocked = false;
+
+  SyncResult.adGateBlocked()
+      : ranSync = false,
+        error = null,
+        adGateBlocked = true;
 }
 
 /// Orchestrates one round of sync against the shared cloud folder — same
@@ -144,14 +159,16 @@ class CloudSyncService {
   ///
   /// [beforeUpload], if given, is awaited once — after any pull/merge of
   /// remote changes has finished, but before anything local gets uploaded
-  /// (pending receipt photos or the database snapshot itself). This is the
-  /// one hook [AppState] uses to show the app's single ad placement, since
-  /// it's meant to run before *pushing* local data up, not before *pulling*
-  /// remote data down.
+  /// (pending receipt photos or the database snapshot itself) — and its
+  /// result decides whether the upload happens at all. This is the hook
+  /// [AppState] uses to gate uploads behind the app's ad placement: a
+  /// `false` return means the gate is closed (see [AdService.showGateAd])
+  /// and this call returns [SyncResult.adGateBlocked] without uploading
+  /// anything, having still pulled/merged whatever the remote side had.
   Future<SyncResult> syncNow({
     bool keepLocalReceiptCopies = false,
     Duration staleLockAge = const Duration(minutes: 10),
-    Future<void> Function()? beforeUpload,
+    Future<bool> Function()? beforeUpload,
   }) async {
     final appFolderId = _appFolderId;
     if (!provider.isSignedIn || appFolderId == null) {
@@ -180,8 +197,8 @@ class CloudSyncService {
         await _pullAndMerge(session, remoteInfo.id);
       }
 
-      if (beforeUpload != null) {
-        await beforeUpload();
+      if (beforeUpload != null && !await beforeUpload()) {
+        return SyncResult.adGateBlocked();
       }
 
       final allReceiptsUploaded =