expose current checkpoint request id for retries

Author: stevensJourney

crates/core/src/sync/interface.rs

@@ -289,6 +289,14 @@ pub fn register(db: *mut sqlite::sqlite3, state: Rc<DatabaseState>) -> Result<()
 
                     return Ok(());
                 }
+                "current_checkpoint_request_id" => {
+                    let adapter = state.storage_adapter(db)?;
+                    match adapter.last_checkpoint_request_id()? {
+                        Some(request_id) => ctx.result_int64(request_id),
+                        None => ctx.result_null(),
+                    }
+                    return Ok(());
+                }
                 "line_text" => SyncControlRequest::SyncEvent(SyncEvent::TextLine {
                     data: if payload.value_type() == ColumnType::Text {
                         payload.text()

dart/test/sync_test.dart

@@ -197,6 +197,10 @@ void _syncTests<T>({
     return invokeControlScalar('local_target_op', opId);
   }
 
+  Object? currentCheckpointRequestId() {
+    return invokeControlScalar('current_checkpoint_request_id', null);
+  }
+
   ResultSet fetchRows() {
     return db.select('select * from items');
   }
@@ -462,6 +466,31 @@ void _syncTests<T>({
     expect(lastRequestedCheckpointRequestId(), 3);
   });
 
+  syncTest('reports current checkpoint request id without incrementing', (_) {
+    expect(currentCheckpointRequestId(), isNull);
+
+    invokeControlRaw('start', null);
+    invokeControlRaw('seed_checkpoint_request_id', 1);
+    expect(currentCheckpointRequestId(), 1);
+
+    expect(currentCheckpointRequestId(), 1);
+    expect(nextCheckpointRequestId(), 2);
+    expect(currentCheckpointRequestId(), 2);
+    expect(lastRequestedCheckpointRequestId(), 2);
+
+    pushCheckpoint(buckets: priorityBuckets, writeCheckpoint: '2');
+    pushCheckpointComplete();
+    expect(lastAppliedCheckpointRequestId(), 2);
+    expect(currentCheckpointRequestId(), 2);
+
+    db.execute("insert into items (id, col) values ('local', 'data');");
+    expect(lastAppliedCheckpointRequestId(), isNull);
+    expect(currentCheckpointRequestId(), 2);
+
+    expect(nextCheckpointRequestId(), 3);
+    expect(currentCheckpointRequestId(), 3);
+  });
+
   syncTest('seeds requested checkpoint request ids from service state', (_) {
     final startInstructions = invokeControlRaw('start', null);
     expect(streamLastCheckpointRequestId(startInstructions), isNull);

docs/sync.md

@@ -38,11 +38,14 @@ The following commands are supported:
 10. `next_checkpoint_request_id`: No payload. During an active sync iteration after checkpoint
     request state exists locally, allocates and returns the next checkpoint request id as an
     integer result.
-11. `local_target_op`: Payload is `null`, an integer, or an integer string. Probes, updates or
+11. `current_checkpoint_request_id`: No payload. Returns the current checkpoint request sequence
+    value as an integer result, or SQL `NULL` if absent. This command does not allocate a new id and
+    can run outside a sync iteration.
+12. `local_target_op`: Payload is `null`, an integer, or an integer string. Probes, updates or
     clears the local target op and returns the previously-observed value as an integer result, or
     SQL `NULL` if there was no target. This command can run outside of a sync iteration and does not
     affect it.
-12. `seed_checkpoint_request_id`: Payload is a positive integer or integer string. After receiving
+13. `seed_checkpoint_request_id`: Payload is a positive integer or integer string. After receiving
     `EstablishSyncStream`, SDKs should reconcile the local hint with service-side
     checkpoint-request state, then seed core with the accepted positive id.
 
@@ -62,13 +65,17 @@ 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.
+- To retry a checkpoint request without incrementing the counter, read
+  `powersync_control('current_checkpoint_request_id', NULL)` and repost that id when the SDK's
+  runtime last-applied checkpoint request id is absent or lower.
 - Resolve explicit checkpoint waiters from `DidCompleteSync.applied_checkpoint_request_id`. SDKs
   that drive waiters from status snapshots can also watch
   `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.
-`next_checkpoint_request_id` and `local_target_op` return scalar values directly.
+`next_checkpoint_request_id`, `current_checkpoint_request_id` and `local_target_op` return values
+directly.
 
 ```typescript
 type Instruction = { LogLine: LogLine }

docs/write-checkpoint-requests.md

@@ -59,6 +59,16 @@ the service lost its record, posting the local hint recreates the service-side s
 seeded request counter. SDKs should wait for the connection reconciliation and seed step before
 creating checkpoint requests.
 
+To retry an existing checkpoint request without advancing the counter, SDKs can read:
+
+```text
+powersync_control('current_checkpoint_request_id', NULL)
+```
+
+Core returns the current sequence value as a SQLite integer, or SQL `NULL` when the counter has not
+been seeded. SDKs can compare this with their runtime last-applied checkpoint request id and repost
+the current id when the applied id is absent or lower.
+
 ## Local Write Gate
 
 A local write records CRUD and sets:
@@ -145,6 +155,13 @@ checkpoint state.
   to the service, retrying posts the same id again, which is safe because the service treats the
   latest posted id as effective state.
 
+`powersync_control('current_checkpoint_request_id', NULL)`
+
+- Returns: current checkpoint request sequence value as a SQLite integer, or SQL `NULL` if absent.
+- Does not allocate a new id.
+- SDKs should compare this with their runtime last-applied checkpoint request id to decide whether
+  to repost the current id.
+
 `powersync_control('local_target_op', value)`
 
 - Payload `NULL`: return current target without changing it.