improve comments

src/swarm-engine/Swarm/Game/CESK.hs

@@ -163,7 +163,8 @@ data Frame
     FRcd Env [(Var, Value)] Var [(Var, Maybe Term)]
   | -- | We are in the middle of evaluating a record field projection.
     FProj Var
-  | -- | We should suspend once we finish the current evaluation.
+  | -- | We should suspend with the given environment once we finish
+    --   the current evaluation.
     FSuspend Env
   | -- | If an exception bubbles all the way up to this frame, then
     --   switch to Suspended mode with this saved top-level context.
@@ -359,7 +360,23 @@ initMachine t = In (prepareTerm mempty t) mempty emptyStore [FExec]
 --   term is suitable for execution by the base (REPL) robot.
 continue :: TSyntax -> CESK -> CESK
 continue t = \case
+  -- The normal case is when we are continuing from a suspended state. We:
+  --
+  --   (1) insert a suspend call at the end of the term, so that in
+  --   the normal case after executing the entire term we will suspend
+  --   in the innermost scope, to continue executing another term
+  --   within that scope later.
+  --
+  --   (2) insert a failsafe FRestoreEnv frame into the continuation
+  --   stack, in case execution of the term throws an exception.  In
+  --   that case we will fall back to suspending with the original
+  --   environment e (any names brought into scope by executing the
+  --   term will be discarded).  If the term succeeds, the extra
+  --   FRestoreEnv frame will be discarded.
   Suspended _ e s k -> In (insertSuspend $ prepareTerm e t) e s (FExec : FRestoreEnv e : k)
+  -- In any other state, just start with an empty environment.  This
+  -- happens e.g. when running a program on the base robot for the
+  -- very first time.
   cesk -> In (insertSuspend $ prepareTerm mempty t) mempty (cesk ^. store) (FExec : (cesk ^. cont))
 
 -- | Prepare a term for evaluation by a CESK machine in the given

src/swarm-engine/Swarm/Game/Step.hs

@@ -767,7 +767,15 @@ stepCESK cesk = case cesk of
   -- If we're suspended but we were on the LHS of a bind, switch to
   -- evaluating that, except with the environment from the suspension
   -- instead of the environment stored in the FBind frame, as if the
-  -- RHS of the bind had been grafted in right where the suspend was.
+  -- RHS of the bind had been grafted in right where the suspend was,
+  -- i.e. the binds were reassociated.  For example
+  --
+  -- (x; z <- y; suspend z); q; r
+  --
+  -- should be equivalent to
+  --
+  -- x; z <- y; q; r
+  --
   Suspended _ e s (FBind Nothing _ t2 _ : k) -> return $ In t2 e s (FExec : k)
   Suspended v e s (FBind (Just x) mtr t2 _ : k) -> do
     let e' = case mtr of
@@ -790,6 +798,9 @@ stepCESK cesk = case cesk of
   -- If raising an exception up the stack and we reach the top, handle
   -- it appropriately.
   Up exn s [] -> handleException exn s Nothing
+  -- If we are raising an exception up the stack and we see an
+  -- FRestoreEnv frame, log the exception, switch into a suspended state,
+  -- and discard the rest of the stack.
   Up exn s (FRestoreEnv e : _) -> handleException exn s (Just e)
   -- If an atomic block threw an exception, we should terminate it.
   Up exn s (FFinishAtomic : k) -> do
@@ -800,9 +811,6 @@ stepCESK cesk = case cesk of
   -- block.
   Up exn s (FTry c : k)
     | isCatchable exn -> return $ Out c s (FApp (VCApp Force []) : FExec : k)
-  -- If we are raising an exception up the stack and we see an FRestoreEnv frame,
-  -- switch into a suspended state.
-
   -- Otherwise, keep popping from the continuation stack.
   Up exn s (_ : k) -> return $ Up exn s k
   -- Finally, if we're done evaluating and the continuation stack is