From 1b0a0504546a45b77f7c0fdb2d2a74b79f9427a7 Mon Sep 17 00:00:00 2001
From: zibo-chen <58510061+zibo-chen@users.noreply.github.com>
Date: Thu, 24 Sep 2026 03:15:35 -0600
Subject: [PATCH 1/2] Add remote file change cursor and stable entry identity

---
 proto/files.proto | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/proto/files.proto b/proto/files.proto
index 341f08e..e4bf8c6 100644
--- a/proto/files.proto
+++ b/proto/files.proto
@@ -45,6 +45,8 @@ message RemoteFileEntryInfo {
   RemoteFileEntryKind kind = 3;
   uint64 size = 4;
   int64 modified_at_ms = 5;
+  string revision = 6;
+  string id = 7;
 }
 
 message RemoteFileListSharesRequest {}
@@ -135,6 +137,14 @@ message RemoteFileConditionalUploadRequest {
   string expected_revision = 5;
 }
 
+// A long-poll cursor for changes to a shared folder. A new epoch means the
+// caller must reconcile its previously enumerated directories before waiting.
+message RemoteFileWatchChangesRequest {
+  string share_id = 1;
+  string epoch = 2;
+  uint64 after_sequence = 3;
+}
+
 message RemoteFileRequestFrame {
   oneof body {
     RemoteFileListSharesRequest list_shares = 10;
@@ -150,6 +160,7 @@ message RemoteFileRequestFrame {
     RemoteFileReadRangeRequest read_range = 20;
     RemoteFileConditionalUploadRequest conditional_upload = 21;
     RemoteFileConditionalDeleteRequest conditional_delete = 22;
+    RemoteFileWatchChangesRequest watch_changes = 23;
   }
 }
 
@@ -165,6 +176,10 @@ message RemoteFileResponseFrame {
   optional RemoteFileErrorCode error_code = 9;
   string revision = 10;
   bytes range_data = 11;
+  string change_epoch = 12;
+  uint64 change_sequence = 13;
+  repeated string changed_directories = 14;
+  bool change_reset = 15;
 }
 
 enum RemoteFileErrorCode {

From e51fa5dbf2c9ba11129340b433efb56460d34a4c Mon Sep 17 00:00:00 2001
From: zibo-chen <58510061+zibo-chen@users.noreply.github.com>
Date: Thu, 24 Sep 2026 03:29:22 -0600
Subject: [PATCH 2/2] Document remote file revision and cursor semantics

---
 proto/files.proto | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/proto/files.proto b/proto/files.proto
index e4bf8c6..783ac58 100644
--- a/proto/files.proto
+++ b/proto/files.proto
@@ -45,7 +45,9 @@ message RemoteFileEntryInfo {
   RemoteFileEntryKind kind = 3;
   uint64 size = 4;
   int64 modified_at_ms = 5;
+  // The revision changes when the entry content or metadata changes.
   string revision = 6;
+  // The ID stays stable when the entry is renamed within the share.
   string id = 7;
 }
 
@@ -177,6 +179,7 @@ message RemoteFileResponseFrame {
   string revision = 10;
   bytes range_data = 11;
   string change_epoch = 12;
+  // Sequence numbers are scoped to change_epoch.
   uint64 change_sequence = 13;
   repeated string changed_directories = 14;
   bool change_reset = 15;