expose internal_last_applied_checkpoint_request_id in the sync status.

Author: stevensJourney

crates/core/src/sync/storage_adapter.rs

@@ -134,7 +134,7 @@ impl StorageAdapter {
             downloading: None,
             streams,
             // Checkpoint requests should not be made or compared while offline.
-            internal_applied_checkpoint_request_id: None,
+            internal_last_applied_checkpoint_request_id: None,
         })
     }
 

crates/core/src/sync/streaming_sync.rs

@@ -967,6 +967,13 @@ impl StreamingSyncIteration {
         timestamp: TimestampMicros,
         applied_checkpoint_request_id: Option<i64>,
     ) {
+        if let Some(request_id) = applied_checkpoint_request_id {
+            event.instructions.push(Instruction::LogLine {
+                severity: LogSeverity::DEBUG,
+                line: format!("Applied checkpoint request id {request_id}").into(),
+            });
+        }
+
         event.instructions.push(Instruction::DidCompleteSync {
             applied_checkpoint_request_id,
         });

crates/core/src/sync/sync_status.rs

@@ -53,11 +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.
+    /// Runtime-only request id from the most recent applied checkpoint request.
     ///
     /// 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>,
+    pub internal_last_applied_checkpoint_request_id: Option<i64>,
 }
 
 impl DownloadSyncStatus {
@@ -72,13 +72,14 @@ impl DownloadSyncStatus {
         self.connected = false;
         self.connecting = false;
         self.downloading = None;
+        self.internal_last_applied_checkpoint_request_id = None;
     }
 
     pub fn start_connecting(&mut self) {
         self.connected = false;
         self.downloading = None;
         self.connecting = true;
-        self.internal_applied_checkpoint_request_id = None;
+        self.internal_last_applied_checkpoint_request_id = None;
         self.debug_assert_priority_status_is_sorted();
     }
 
@@ -137,7 +138,7 @@ impl DownloadSyncStatus {
             has_synced: Some(true),
         });
 
-        self.internal_applied_checkpoint_request_id = applied_checkpoint_request_id;
+        self.internal_last_applied_checkpoint_request_id = applied_checkpoint_request_id;
     }
 }
 
@@ -149,7 +150,7 @@ impl Default for DownloadSyncStatus {
             downloading: None,
             priority_status: Vec::new(),
             streams: Vec::new(),
-            internal_applied_checkpoint_request_id: None,
+            internal_last_applied_checkpoint_request_id: None,
         }
     }
 }
@@ -193,15 +194,17 @@ impl Serialize for DownloadSyncStatus {
             }
         }
 
-        let field_count = 5 + usize::from(self.internal_applied_checkpoint_request_id.is_some());
+        let field_count =
+            5 + usize::from(self.internal_last_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)?;
+        if let Some(request_id) = self.internal_last_applied_checkpoint_request_id {
+            serializer
+                .serialize_field("internal_last_applied_checkpoint_request_id", &request_id)?;
         }
 
         serializer.end()

dart/test/sync_test.dart

@@ -407,7 +407,7 @@ void _syncTests<T>({
           containsPair(
               'status',
               containsPair(
-                  'internal_applied_checkpoint_request_id', anything))))),
+                  'internal_last_applied_checkpoint_request_id', anything))))),
     );
     expect(
       instructions,
@@ -624,8 +624,8 @@ void _syncTests<T>({
             'UpdateSyncStatus',
             containsPair(
                 'status',
-                containsPair(
-                    'internal_applied_checkpoint_request_id', anything))))),
+                containsPair('internal_last_applied_checkpoint_request_id',
+                    anything))))),
       );
       expect(lastAppliedCheckpointRequestId(), isNull);
 
@@ -652,13 +652,18 @@ void _syncTests<T>({
         ),
       ),
     );
+    expect(
+      appliedInstructions,
+      contains(containsPair('LogLine',
+          {'severity': 'DEBUG', 'line': 'Applied checkpoint request id 1'})),
+    );
     expect(
       appliedInstructions,
       contains(containsPair(
         'UpdateSyncStatus',
         containsPair(
           'status',
-          containsPair('internal_applied_checkpoint_request_id', 1),
+          containsPair('internal_last_applied_checkpoint_request_id', 1),
         ),
       )),
     );
@@ -678,7 +683,7 @@ void _syncTests<T>({
           containsPair(
               'status',
               containsPair(
-                  'internal_applied_checkpoint_request_id', anything))))),
+                  'internal_last_applied_checkpoint_request_id', anything))))),
     );
 
     final [row] = db.select('select powersync_offline_sync_status();');
@@ -691,6 +696,29 @@ void _syncTests<T>({
         db.select(r"SELECT * FROM ps_buckets WHERE name = '$local'"), isEmpty);
   });
 
+  syncTest('disconnect clears applied checkpoint request id from status', (_) {
+    invokeControl('start', null);
+
+    pushCheckpoint(buckets: priorityBuckets, writeCheckpoint: '1');
+    pushCheckpointComplete();
+
+    final instructions = invokeControl('stop', null);
+    expect(
+      instructions,
+      contains(containsPair(
+        'UpdateSyncStatus',
+        containsPair(
+          'status',
+          allOf(
+            containsPair('connected', false),
+            isNot(containsPair(
+                'internal_last_applied_checkpoint_request_id', anything)),
+          ),
+        ),
+      )),
+    );
+  });
+
   syncTest('local writes clear checkpoint request high-water marks', (_) {
     invokeControl('start', null);
 
@@ -1160,7 +1188,13 @@ void _syncTests<T>({
 
       // Now complete the upload process.
       probeLocalTargetOp(1);
-      invokeControl('completed_upload', null);
+      final uploadCompleteInstructions =
+          invokeControl('completed_upload', null);
+      expect(
+        uploadCompleteInstructions,
+        contains(containsPair('LogLine',
+            {'severity': 'DEBUG', 'line': 'Applied checkpoint request id 1'})),
+      );
 
       // This should apply the pending write checkpoint.
       expect(fetchRows(), [

docs/sync.md

@@ -64,7 +64,7 @@ what SDKs need to do.
   ids; it does not update that gate.
 - 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
+  `UpdateSyncStatus.status.internal_last_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.
@@ -107,7 +107,7 @@ interface UpdateSyncStatus {
   priority_status: [],
   downloading: null | DownloadProgress,
   streams: [],
-  internal_applied_checkpoint_request_id?: number,
+  internal_last_applied_checkpoint_request_id?: number,
 }
 
 interface DidCompleteSync {

docs/write-checkpoint-requests.md

@@ -121,10 +121,12 @@ 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.
+Core also includes the applied request id in
+`UpdateSyncStatus.status.internal_last_applied_checkpoint_request_id` when a status update follows a
+checkpoint apply with a `write_checkpoint`. Later status updates without an applied request id,
+including disconnect updates, clear the field. SDKs may use this for status-stream waiters, but
+should treat it as internal, runtime-only state rather than app-visible progress or persisted
+checkpoint state.
 
 ## Control Commands