add prevEntered pointer

Client requires this always point to the previous Entered it accepted,
so a hash chain of Entered is built up, and there is no possibility for
ambiguity about which order a client received two Entered activies in.

So restoreHashes now has to try every possible combination of
known hashes for both prevEntered and prevActivity. That could be
significantly more work, but it would be unusual for there to be a lot
of known hashes, so it should be ok.

--graphviz shows this additional hash chain with grey edges
(and leaves out edges identical to the other hash chain)

While testing this with an artifical network lag, it turned out that
signature verification was failing for Reject messages sent by the
user. Didn't quite figure out what was at the bottom of that,
but the Activity Entered that was sent back in a Reject message was
clearly not useful, because it probably had both its prevEntered and
prevActivity hashes set to Nothing (because restoreHashes didn't restore
them, because the original Activity Entered was out of the expected
chain). So, switched Rejected to use a Hash.

(And renamed Rejected to EnteredRejected to make it more clear what
it's rejecting.)

Also, added a lastAccepted hash to EnteredRejected. This lets
the developer find its way back to the accepted chain when some
of its input gets rejected.

This commit was sponsored by Trenton Cronholm on Patreon.

1 files changed, 37 insertions, 27 deletions

diff --git a/doc/protocol.mdwn b/doc/protocol.mdwn
index 5a0e679..2c4887e 100644
--- a/doc/protocol.mdwn
+++ b/doc/protocol.mdwn
@@ -16,13 +16,12 @@ Seen messages, and the developer responds with Activity Entered.
 There are also Control messages, which can be sent by either
 party at any time, and do not affect IO to the console.
 
-The first message in a debug-me session is a Control sent by the
-user, which establishes a session key (see below for details). The second
-message is an Activity Seen.
-
-Activity Seen and Activity Entered messages have a prevActivity,
-which points to the Hash of a previous Activity. (And is Nothing for the
-first Activity Seen.) So a chain of messages is built up.
+Activity Seen and Activity Entered messages have a prevActivity field,
+which points to the Hash of a previous Activity either Seen or Entered.
+There is also a prevEntered field, which points to the Hash of the most
+recent Activity Entered. (prevActivity is Nothing for the first Activity
+Seen, and prevEntered is Nothing until the developer enters something.)
+So a chain of messages is built up.
 
 (The exact details about how objects are hashed is not described here; see
 [Hash.hs](http://source.debug-me.branchable.com/?p=source.git;a=blob;f=Hash.hs;hb=HEAD)
@@ -43,21 +42,24 @@ entering "y" in response to "Display detailed reactor logs?" at the same time
 that a new "Vent core to atmosphere?" question was being displayed!
 The debug-me protocol is designed to prevent such conflicts of opinion.
 
-The user only processes a new Activity Entered when it meets one of these
+The user only accepts a new Activity Entered when it meets one of these
 requirements:
 
 1. The Activity Entered has as its prevActivity the last Activity
-   (Entered or Seen) that the user processed.
+   (Entered or Seen) that the user accepted.
 2. The Activity Entered has as its prevActivity an older Activity
-   that the user processed, and its echoData matches the concacenation
+   that the user accepted, and its echoData matches the concacenation
    of every Activity Seen after the prevActivity, up to the most recent
    Activity Seen.
 
    (This allows the developer to enter a command quickly without waiting
    for each letter to echo back to them.)
 
+An Activity Entered must also have as its prevEntered field the hash of
+the last Activity Entered that was accepted, unless there have been none yet.
+
 When an Activity Entered does not meet these rules, the user sends
-it back in a Rejected message to let the developer know the input was not
+back a EnteredRejected message to let the developer know the input was not
 allowed.
 
 The developer also checks the prevActivity of Activity Seen messages it
@@ -70,19 +72,27 @@ messages. The developer accepts a new Activity Seen when either:
    that the developer generated, after the last Activity Seen
    that the developer accepted.
 
-At the start of the debug-me session, Ed25519 session key pairs are
-generated by both the user and the developer. The first message
-in the protocol is the user sending their session pubic key
-in a Control message containing a SessionKey.
+(The developer does not check the prevEntered field of Activity Seen,
+however, the user should set it. When there are multiple developers,
+this helps one developer know when the user has accepted an Activity
+Entered from another developer.)
+
+## session startup
+
+At the start of the debug-me session, an Ed25519 session key pair are
+generated by the user. The first message in the protocol is the user
+sending their session pubic key in a Control message containing their
+SessionKey. The second message is an Activity Seen.
 
-Before the developer can enter anything, they must send a SessionKey message
-with their session key, and it must be accepted by the user. The developer
-must have a gpg private key, which is used to sign their session key. 
-(The user may have a gpg private key, which may sign their session key
-if available, but this is optional.) The user will reject session keys
-that are not signed by a gpg key or when the gpg key is not one they
-trust. The user sends a SessionKeyAccepted/SessionKeyRejected control
-message to indicate if they accepted the developer's key or not.
+The developer also has a Ed25519 session key pair. Before the developer can
+enter anything, they must send a SessionKey message with their session key,
+and it must be accepted by the user. The developer must have a gpg private
+key, which is used to sign their session key. (The user may have a gpg
+private key, which may sign their session key if available, but this is
+optional.) The user will reject session keys that are not signed by a gpg
+key or when the gpg key is not one they trust. The user sends a
+SessionKeyAccepted/SessionKeyRejected control message to indicate if they
+accepted the developer's key or not.
 
 Each message in the debug-me session is signed by the party that sends it,
 using their session key. The hash of a message includes its signature, so
@@ -93,7 +103,7 @@ Note that there could be multiple developers, in which case each will
 send their session key before being able to do anything except observe
 the debug-me session.
 
-The prevActivity hash is actually not included in the data sent across the
-wire. It's left out to save space, and gets added back in by the receiver.
-The receiver uses the signature of the message to tell when it's found
-the right prevActivity hash to add back in.
+The prevActivity and prevEntered hashes are actually not included in the
+data sent across the wire. They are left out to save space, and get
+added back in by the receiver. The receiver uses the signature of the
+message to tell when it's found the right hashes to add back in.