Add discussion of version numbers.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>

diff --git a/docs/proposed/magic-folder/remote-to-local-sync.rst b/docs/proposed/magic-folder/remote-to-local-sync.rst
index 5df9ed2a730b82507e7b0e286379412b9e58039e..90573967d99a8c2e2b5ef032c71b7722dfa23c02 100644 (file)
--- a/docs/proposed/magic-folder/remote-to-local-sync.rst
+++ b/docs/proposed/magic-folder/remote-to-local-sync.rst
@@ -170,6 +170,13 @@ collapsed into the same DMD, which could get quite large. In practice a
 single DMD can easily handle the number of files expected to be written
 by a client, so this is unlikely to be a significant issue.
 
+123‒ ‒ ‒: In these designs, the set of files in a Magic Folder is
+represented as the union of the files in all client DMDs. However,
+when a file is modified by more than one client, it will be linked
+from multiple client DMDs. We therefore need a mechanism, such as a
+version number or a monotonically increasing timestamp, to determine
+which copy takes priority.
+
 35‒ ‒: When a Magic Folder client detects a remote change, it must
 traverse an immutable directory structure to see what has changed.
 Completely unchanged subtrees will have the same URI, allowing some of
@@ -220,6 +227,8 @@ leave some corner cases of the write coordination problem unsolved.
 +------------------------------------------------+------+------+------+------+------+------+
 | Can result in large DMDs                       |‒     |      |      |      |      |      |
 +------------------------------------------------+------+------+------+------+------+------+
+| Need version number to determine priority      |‒     |‒     |‒     |      |      |      |
++------------------------------------------------+------+------+------+------+------+------+
 | Must traverse immutable directory structure    |      |      |‒ ‒   |      |‒ ‒   |      |
 +------------------------------------------------+------+------+------+------+------+------+
 | Must traverse mutable directory structure      |      |‒ ‒   |      |‒ ‒   |      |      |
@@ -260,6 +269,10 @@ Therefore, design 1 was chosen. That is:
     of each file encodes the full subpath of that file relative to the
     Magic Folder.
 
+Each directory entry in a DMD also stores a version number, so that the
+latest version of a file is well-defined when it has been modified by
+multiple clients.
+
 We want to enable dynamic configuration of the set of clients subscribed
 to a Magic Folder, without having to reconfigure or restart each client
 when another client joins or leaves. To support this, we have a single