From ee8a21e1661f35f04a19cb9f3412d7ea162c4344 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C5=8Dshin?= <git@wholezero.org>
Date: Thu, 10 Feb 2022 23:32:21 -0800
Subject: [PATCH] conn: more docs cleanup, describe %ovum updates

---
 pkg/urbit/vere/io/conn.c | 35 +++++++++++++++++++++--------------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/pkg/urbit/vere/io/conn.c b/pkg/urbit/vere/io/conn.c
index 98bc01de07..9f1f5585d7 100644
--- a/pkg/urbit/vere/io/conn.c
+++ b/pkg/urbit/vere/io/conn.c
@@ -35,7 +35,7 @@
 **
 **  responses to %fyrd are either %fail if something went wrong
 **  in the driver, or %avow to indicate success or failure from
-**  %khan. +avow is: (each (cask) goof).
+**  %khan. $avow is: (each (cask) goof).
 **
 **  %peek is a namespace read request (aka scry), and will be
 **  forwarded directly to arvo. its arguments are the nom of the
@@ -49,16 +49,26 @@
 **
 **  %peel is a runtime "peek". it exposes an unprincipled
 **  scry-like namespace allowing querying of various metrics
-**  about the state of vere. /help produces a list of available
-**  commands. /args produces the command-line arguments used to
-**  start vere. /vars produces runtime metrics at the moment in
-**  time that the request was received.
+**  about the state of vere. it accepts $path-like arguments,
+**  i.e. nul-terminated lists of $knot. it responds as scry
+**  does, with a (unit (unit)), where ~ means "request was not
+**  understood" and [~ ~] means "request understood; empty
+**  response."
+**
+**  the %peek path /help produces a list of available commands.
+**  /args produces the command-line arguments used to start vere.
+**  /vars produces runtime metrics at the moment in time that the
+**  request was received.
 **
 **  %ovum is a raw kernel move, to be injected directly into
 **  arvo. needless to say this will void your warranty. usually
-**  you want to use %fyrd instead.
+**  you want to use %fyrd instead. updates will be sent tracking
+**  the ovum lifecycle: %work when work begins, %done when it
+**  is finished, %drop if it is dropped, and %bail with a stack
+**  trace if it fails.
 **
-**  %urth is a command for the runtime.
+**  %urth is a command for the runtime. these are acked with %.y
+**  on receipt. no further updates are provided.
 **
 **  messages use newt framing. because the framing begins with
 **  a magic byte (^I, horizontal tab), any messages that do not
@@ -420,13 +430,7 @@ _conn_ovum_news(u3_ovum* egg_u, u3_ovum_news new_e)
   }
 }
 
-/* _conn_read_peel(): produces response to a %peel request.
-**
-**  %peel is a runtime scry-like interface. it accepts $path-like
-**  arguments, i.e. nul-terminated lists of $knot. it responds
-**  as scry does, with a (unit (unit)), where ~ means "request
-**  was not understood" and `~ means "request understood; empty
-**  response".
+/* _conn_read_peel(): response to a %peel request, sans rid.
 */
 static u3_noun
 _conn_read_peel(u3_conn* con_u, u3_noun dat)
@@ -498,6 +502,9 @@ _conn_read_peel(u3_conn* con_u, u3_noun dat)
       //
       case c3__vars: {
         if ( c3n == u3K.pir_u->liv_o ) {
+          //  empty response if pier is not yet live, since ames
+          //  state may not yet be wired up.
+          //
           res = u3nc(u3_nul, u3_nul);
           break;
         }