add internal_applied_checkpoint_request_id to sync status

Author: stevensJourney

crates/core/src/sync/storage_adapter.rs

@@ -133,6 +133,8 @@ impl StorageAdapter {
             priority_status: priority_items,
             downloading: None,
             streams,
+            // Checkpoint requests should not be made or compared while offline.
+            internal_applied_checkpoint_request_id: None,
         })
     }
 

crates/core/src/sync/streaming_sync.rs

@@ -972,7 +972,7 @@ impl StreamingSyncIteration {
         });
 
         self.status.update(
-            |status| status.applied_checkpoint(timestamp),
+            |status| status.applied_checkpoint(timestamp, applied_checkpoint_request_id),
             &mut event.instructions,
         );
     }

crates/core/src/sync/sync_status.rs

@@ -53,6 +53,11 @@ pub struct DownloadSyncStatus {
     /// received), information about how far the download has progressed.
     pub downloading: Option<SyncDownloadProgress>,
     pub streams: Vec<ActiveStreamSubscription>,
+    /// Runtime-only request id from the most recent full checkpoint apply.
+    ///
+    /// This is exposed in sync status for SDK internals, but it is not persisted and should not be
+    /// treated as user-facing download progress.
+    pub internal_applied_checkpoint_request_id: Option<i64>,
 }
 
 impl DownloadSyncStatus {
@@ -73,6 +78,7 @@ impl DownloadSyncStatus {
         self.connected = false;
         self.downloading = None;
         self.connecting = true;
+        self.internal_applied_checkpoint_request_id = None;
         self.debug_assert_priority_status_is_sorted();
     }
 
@@ -117,7 +123,11 @@ impl DownloadSyncStatus {
         self.debug_assert_priority_status_is_sorted();
     }
 
-    pub fn applied_checkpoint(&mut self, now: TimestampMicros) {
+    pub fn applied_checkpoint(
+        &mut self,
+        now: TimestampMicros,
+        applied_checkpoint_request_id: Option<i64>,
+    ) {
         self.downloading = None;
         self.priority_status.clear();
 
@@ -126,6 +136,8 @@ impl DownloadSyncStatus {
             last_synced_at: Some(now),
             has_synced: Some(true),
         });
+
+        self.internal_applied_checkpoint_request_id = applied_checkpoint_request_id;
     }
 }
 
@@ -137,6 +149,7 @@ impl Default for DownloadSyncStatus {
             downloading: None,
             priority_status: Vec::new(),
             streams: Vec::new(),
+            internal_applied_checkpoint_request_id: None,
         }
     }
 }
@@ -180,12 +193,16 @@ impl Serialize for DownloadSyncStatus {
             }
         }
 
-        let mut serializer = serializer.serialize_struct("DownloadSyncStatus", 5)?;
+        let field_count = 5 + usize::from(self.internal_applied_checkpoint_request_id.is_some());
+        let mut serializer = serializer.serialize_struct("DownloadSyncStatus", field_count)?;
         serializer.serialize_field("connected", &self.connected)?;
         serializer.serialize_field("connecting", &self.connecting)?;
         serializer.serialize_field("priority_status", &self.priority_status)?;
         serializer.serialize_field("downloading", &self.downloading)?;
         serializer.serialize_field("streams", &SerializeStreamsWithProgress(self))?;
+        if let Some(request_id) = self.internal_applied_checkpoint_request_id {
+            serializer.serialize_field("internal_applied_checkpoint_request_id", &request_id)?;
+        }
 
         serializer.end()
     }

dart/test/sync_test.dart

@@ -400,6 +400,15 @@ void _syncTests<T>({
     invokeControl('stop', null);
 
     final instructions = invokeControl('start', null);
+    expect(
+      instructions,
+      isNot(contains(containsPair(
+          'UpdateSyncStatus',
+          containsPair(
+              'status',
+              containsPair(
+                  'internal_applied_checkpoint_request_id', anything))))),
+    );
     expect(
       instructions,
       contains(
@@ -609,6 +618,15 @@ void _syncTests<T>({
         isNot(contains(containsPair('DidCompleteSync',
             containsPair('applied_checkpoint_request_id', anything)))),
       );
+      expect(
+        instructions,
+        isNot(contains(containsPair(
+            'UpdateSyncStatus',
+            containsPair(
+                'status',
+                containsPair(
+                    'internal_applied_checkpoint_request_id', anything))))),
+      );
       expect(lastAppliedCheckpointRequestId(), isNull);
 
       final [row] = db.select('select powersync_offline_sync_status();');
@@ -634,6 +652,16 @@ void _syncTests<T>({
         ),
       ),
     );
+    expect(
+      appliedInstructions,
+      contains(containsPair(
+        'UpdateSyncStatus',
+        containsPair(
+          'status',
+          containsPair('internal_applied_checkpoint_request_id', 1),
+        ),
+      )),
+    );
     expect(lastAppliedCheckpointRequestId(), 1);
 
     pushCheckpoint(buckets: priorityBuckets);
@@ -643,6 +671,15 @@ void _syncTests<T>({
       instructions,
       contains(containsPair('DidCompleteSync', <String, Object?>{})),
     );
+    expect(
+      instructions,
+      isNot(contains(containsPair(
+          'UpdateSyncStatus',
+          containsPair(
+              'status',
+              containsPair(
+                  'internal_applied_checkpoint_request_id', anything))))),
+    );
 
     final [row] = db.select('select powersync_offline_sync_status();');
     expect(

docs/sync.md

@@ -62,8 +62,10 @@ what SDKs need to do.
   id to the service, then store the accepted id with `powersync_control('local_target_op', id)`.
 - `local_target_op` is the apply gate for local writes. `next_checkpoint_request_id` only allocates
   ids; it does not update that gate.
-- Resolve explicit checkpoint waiters from `DidCompleteSync.applied_checkpoint_request_id`, not from
-  `ps_kv`.
+- Resolve explicit checkpoint waiters from `DidCompleteSync.applied_checkpoint_request_id`. SDKs
+  that drive waiters from status snapshots can also watch
+  `UpdateSyncStatus.status.internal_applied_checkpoint_request_id`. Treat that status field as
+  runtime-only SDK state, not persisted checkpoint state or app-visible progress.
 
 Most `powersync_control` commands return a JSON-encoded array of instructions for the client.
 `next_checkpoint_request_id` and `local_target_op` return scalar values directly.
@@ -105,6 +107,7 @@ interface UpdateSyncStatus {
   priority_status: [],
   downloading: null | DownloadProgress,
   streams: [],
+  internal_applied_checkpoint_request_id?: number,
 }
 
 interface DidCompleteSync {

docs/write-checkpoint-requests.md

@@ -121,6 +121,11 @@ DidCompleteSync { applied_checkpoint_request_id?: checkpoint.write_checkpoint }
 SDKs should resolve `requestCheckpoint()` / `waitForSync()` waiters when this value is greater than
 or equal to the requested id.
 
+Core also includes the same applied request id in
+`UpdateSyncStatus.status.internal_applied_checkpoint_request_id` for the status update emitted with
+the completed checkpoint. SDKs may use that for status-stream waiters, but should treat it as
+internal, runtime-only state rather than app-visible progress or persisted checkpoint state.
+
 ## Control Commands
 
 `powersync_control('seed_checkpoint_request_id', id)`