undo docs

docs/src/storage.md

@@ -21,21 +21,63 @@ See [Tasks](./tasks.md) for details on the content of that map.
 
 Every change to the task database is captured as an operation.
 In other words, operations act as deltas between database states.
-Operations are crucial to synchronization of replicas, using a technique known as Operational Transforms.
+Operations are crucial to synchronization of replicas, described in [Synchronization Model](./sync-model.md).
+
+Operations are entirely managed by the replica, and some combinations of operations are described as "invalid" here.
+A replica must not create invalid operations, but should be resilient to receiving invalid operations during a synchronization operation.
 
 Each operation has one of the forms 
 
  * `Create(uuid)`
- * `Delete(uuid)`
- * `Update(uuid, property, value, timestamp)`
+ * `Delete(uuid, oldTask)`
+ * `Update(uuid, property, oldValue, newValue, timestamp)`
+ * `UndoPoint()`
 
 The Create form creates a new task.
 It is invalid to create a task that already exists.
 
 Similarly, the Delete form deletes an existing task.
 It is invalid to delete a task that does not exist.
+The `oldTask` property contains the task data from before it was deleted.
 
-The Update form updates the given property of the given task, where property and value are both strings.
-Value can also be `None` to indicate deletion of a property.
+The Update form updates the given property of the given task, where the property and values are strings.
+The `oldValue` gives the old value of the property (or None to create a new property), while `newValue` gives the new value (or None to delete a property).
 It is invalid to update a task that does not exist.
 The timestamp on updates serves as additional metadata and is used to resolve conflicts.
+
+### Application
+
+Each operation can be "applied" to a task database in a natural way:
+
+ * Applying `Create` creates a new, empty task in the task database.
+ * Applying `Delete` deletes a task, including all of its properties, from the task database.
+ * Applying `Update` modifies the properties of a task.
+ * Applying `UndoPoint` does nothing.
+
+### Undo
+
+Each operation also contains enough information to reverse its application:
+
+ * Undoing `Create` deletes a task.
+ * Undoing `Delete` creates a task, including all of the properties in `oldTask`.
+ * Undoing `Update` modifies the properties of a task, reverting to `oldValue`.
+ * Undoing `UndoPoint` does nothing.
+
+The `UndoPoint` operation serves as a marker of points in the operation sequence to which the user might wish to undo.
+For example, creation of a new task with several properities involves several operations, but is a single step from the user's perspective.
+An "undo" command reverses operations, removing them from the operations sequence, until it reaches an `UndoPoint` operation.
+
+### Synchronizing Operations
+
+After operations are synchronized to the server, they can no longer be undone.
+As such, the [synchronization model](./sync-model.md) uses simpler operations.
+Replica operations are converted to sync operations as follows:
+
+ * `Create(uuid)` -> `Create(uuid)` (no change)
+ * `Delete(uuid, oldTask)` -> `Delete(uuid)`
+ * `Update(uuid, property, oldValue, newValue, timestamp)` -> `Update(uuid, property, newValue, timestamp)`
+ * `UndoPoint()` -> Ø (dropped from operation sequence)
+
+Once a sequence of operations has been synchronized, there is no need to store those operations on the replica.
+The current implementation deletes operations at that time.
+An alternative approach is to keep operations for existing tasks, and provide access to those operations as a "history" of modifications to the task.

docs/src/sync-model.md

@@ -34,6 +34,16 @@ Since the replicas are not connected, each may have additional operations that h
 The synchronization process uses operational transformation to "linearize" those operations.
 This process is analogous (vaguely) to rebasing a sequence of Git commits.
 
+### Sync Operations
+
+The [Replica Storage](./storage.md) model contains additional information in its operations that is not included in operations synchronized to other replicas.
+In this document, we will be discussing "sync operations" of the form
+
+ * `Create(uuid)`
+ * `Delete(uuid)`
+ * `Update(uuid, property, value, timestamp)`
+
+
 ### Versions
 
 Occasionally, database states are given a name (that takes the form of a UUID).