document file: a clean stop marked, and `--keep-actor` writes on as the same actor

A node writes as a fresh Automerge actor at each start, so no change number of an actor
comes twice: one sent before a crash but not yet appended to the document file would
otherwise be made again, differently. An epoch thus gathers a writer per start, and
every transfer of its history carries a signature per writer.

The document file now says when it holds everything the node wrote:

* at a clean stop, after the last append, an empty `Closed` record, only where the
  file is up to the document's heads (ready, not rejoining);
* as a node starts on the file, before anything is written, an empty `Opened` record,
  so a crash from then on leaves a file without the mark;
* the header names the actor the node writes with (`current`).

With `--keep-actor` (off by default; needs `--document-file`), a node starting on a
file that ends with `Closed` writes on as that actor. A crash, a drop, a switch or a
rejoin still starts a fresh one, so an epoch's writers come to one per node plus one
per such event. lifecycle.md says so.

1 files changed, 12 insertions, 0 deletions

diff --git a/src/config/mod.rs b/src/config/mod.rs
index 7df68e7..c0abc09 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -264,6 +264,13 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[
         "This node's document on disk. Read at start: the node resumes with it, ready at once. Kept up to date while ready: changes are appended every --document-append, and the file is rewritten after a switch, a rejoin or a restart, and when the appended changes outgrew it.",
     ),
     option(
+        "keep-actor",
+        Kind::Flag,
+        "BOOL",
+        Some("false"),
+        "Resume writing as the actor this node wrote with before it stopped, if it stopped cleanly (its document file holds everything it wrote then), instead of a fresh one: an epoch then gathers a writer per node and per crash or drop rather than per start, which every transfer of its history carries a signature for. Needs document-file.",
+    ),
+    option(
         "document-append",
         Kind::Duration,
         "DURATION",
@@ -654,6 +661,8 @@ pub(crate) struct Settings {
     pub(crate) genesis: bool,
     pub(crate) state_file: Option<PathBuf>,
     pub(crate) document_file: Option<PathBuf>,
+    #[serde(default)]
+    pub(crate) keep_actor: bool,
     #[serde(
         default = "default_document_append",
         with = "crate::units::duration_option"
@@ -982,6 +991,9 @@ impl Settings {
         if self.document_append.is_zero() || self.document_rewrite.is_zero() {
             bail!("document-append and document-rewrite must be longer than 0");
         }
+        if self.keep_actor && self.document_file.is_none() {
+            bail!("keep-actor needs document-file: it tells whether this node stopped cleanly");
+        }
         if self.keepalive < Duration::from_millis(100) {
             bail!("keepalive must be at least 100ms");
         }