Clarify corner cases in the conflict/overwrite decision.

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 26f1825d4c56a68fc5efaf07b37e76b2340e617a..99d2d81ca9a827e8b002821dc2336bb66e92c8f8 100644 (file)
--- a/docs/proposed/magic-folder/remote-to-local-sync.rst
+++ b/docs/proposed/magic-folder/remote-to-local-sync.rst
@@ -690,9 +690,9 @@ Fire Dragons: Distinguishing conflicts from overwrites
 
 When synchronizing a file that has changed remotely, the Magic Folder
 client needs to distinguish between overwrites, in which the remote
 
 When synchronizing a file that has changed remotely, the Magic Folder
 client needs to distinguish between overwrites, in which the remote

-side was aware of your most recent version and overwrote it with a
-new version, and conflicts, in which the remote side was unaware of
-your most recent version when it published its new version. Those two
+side was aware of your most recent version (if any) and overwrote it
+with a new version, and conflicts, in which the remote side was unaware
+of your most recent version when it published its new version. Those two

 cases have to be handled differently — the latter needs to be raised
 to the user as an issue the user will have to resolve and the former
 must not bother the user.
 cases have to be handled differently — the latter needs to be raised
 to the user as an issue the user will have to resolve and the former
 must not bother the user.


@@ -776,12 +776,11 @@ Let ``last_downloaded_uri`` be the field of that name obtained from
 the directory entry metadata for ``foo`` in Bob's DMD (this field
 may be absent). Then the algorithm is:
 
 the directory entry metadata for ``foo`` in Bob's DMD (this field
 may be absent). Then the algorithm is:
 

-* 2a. If Alice has no local copy of ``foo``, classify as an overwrite.
+* 2a. Attempt to "stat" ``foo`` to get its *current statinfo* (size
+  in bytes, ``mtime``, and ``ctime``). If Alice has no local copy
+  of ``foo``, classify as an overwrite.

 
 

-* 2b. Otherwise, "stat" ``foo`` to get its *current statinfo* (size
-  in bytes, ``mtime``, and ``ctime``).
-
-* 2c. Read the following information for the path ``foo`` from the
+* 2b. Read the following information for the path ``foo`` from the

   local magic folder db:
 
   * the *last-uploaded statinfo*, if any (this is the size in
   local magic folder db:
 
   * the *last-uploaded statinfo*, if any (this is the size in


@@ -791,11 +790,12 @@ may be absent). Then the algorithm is:
     for this file, which is the URI under which the file was last
     uploaded.
 
     for this file, which is the URI under which the file was last
     uploaded.
 

-* 2d. If any of the following are true, then classify as a conflict:
+* 2c. If any of the following are true, then classify as a conflict:

 
   * there are pending notifications of changes to ``foo``;
 
   * there are pending notifications of changes to ``foo``;

-  * the last-uploaded statinfo is either absent, or different
-    from the current statinfo;
+  * the last-uploaded statinfo is either absent (i.e. there is no
+    entry in the database for this path), or different from the
+    current statinfo;

   * either ``last_downloaded_uri`` or ``last_uploaded_uri``
     (or both) are absent, or they are different.
 
   * either ``last_downloaded_uri`` or ``last_uploaded_uri``
     (or both) are absent, or they are different.