vere: add %nara %hela hints, add a hoon test module for hints

nara: swedish for near, provides a trace from the start of the nearest virtualization
      to the statement wrapped by the nara hint.

hela: swedish for whole, provides a trace from the start of the event
      to the statement wrapped by the hela hint.

The eventual goal is to present these traces in a way that is most salient & useful to developers
and in a way that is aesthetically pleasing as the bout hint is useful and nice looking.

For this pull request the goal is to provide the actual functionality in code that we can feel
safe and comfortable adding to the master branch. To this end, I've added a trivial set of tests for
nara and hela in pkg/arvo/tests/run/hints.hoon - they only prove that invoking these hints will not
crash the runtime, but I'm open to ideas for how I can test these hints further.

pkg/arvo/tests/run/hints.hoon

@@ -0,0 +1,16 @@
+::  Test that these hints do not crash the runtime
+::    we only test the dynamic hints here
+::    also, there is no need to include the hints for dynamic %bout
+::    since all hoon tests exersize dynamic %bout
+|%
+::  this tests that the short trace hint
+::  is safe to run or ignore
+++  test-nara
+  ~>  %nara.[1 leaf+"nara trace hint test"]
+  ~
+::  this tests that the full trace hint
+::  is safe to run or ignore
+++  test-hela
+  ~>  %hela.[1 leaf+"hela trace hint test"]
+  ~
+--

pkg/urbit/include/all.h

@@ -21,11 +21,11 @@
 #   include "noun/jets.h"      //  u3j: jet control
 #   include "noun/log.h"       //  u3l: logging
 #   include "noun/manage.h"    //  u3m: master state
-#   include "noun/trace.h"     //  u3t: profiling / tracing
 #   include "noun/nock.h"      //  u3n: nock execution
 #   include "noun/options.h"   //  u3o: config options
 #   include "noun/retrieve.h"  //  u3r: noun access (error returns)
 #   include "noun/serial.h"    //  u3s: serialization
+#   include "noun/trace.h"     //  u3t: profiling / tracing
 #   include "noun/xtract.h"    //  u3x: noun access (error crashes)
 #   include "noun/urth.h"      //  u3u: off-loom integration
 #   include "noun/vortex.h"    //  u3v: arvo kernel

pkg/urbit/include/c/motes.h

@@ -771,7 +771,7 @@
 #   define c3__nap    c3_s3('n','a','p')
 #   define c3__narv   c3_s4('n','a','r','v')
 #   define c3__ne     c3_s2('n','e')
-#   define c3__near   c3_s4('n','e', 'a', 'r')
+#   define c3__nara   c3_s4('n', 'a', 'r', 'a')
 #   define c3__need   c3_s4('n','e','e','d')
 #   define c3__neft   c3_s4('n','e','f','t')
 #   define c3__nest   c3_s4('n','e','s','t')

pkg/urbit/noun/manage.c

@@ -1796,8 +1796,7 @@ u3m_boot(c3_c* dir_c)
   if ( c3n == nuu_o ) {
     u3j_ream();
     u3n_ream();
-    // TODO: remove me before PR
-    u3m_reclaim();
+
     return u3A->eve_d;
   }
   else {

pkg/urbit/noun/nock.c

@@ -453,7 +453,7 @@ _n_nock_on(u3_noun bus, u3_noun fol)
 #define KICS 54
 #define TICB 55
 #define TICS 56
-// nock 11
+// nock 12
 #define WILS 57
 #define WISH 58
 // hint processing
@@ -1020,7 +1020,7 @@ _n_bint(u3_noun* ops, u3_noun hif, u3_noun nef, c3_o los_o, c3_o tel_o)
       default: {
         return _n_comp(ops, nef, los_o, tel_o);
       }
-      case c3__near:
+      case c3__nara:
       case c3__hela:
       case c3__bout: {
         u3_noun fen = u3_nul;
@@ -1056,7 +1056,7 @@ _n_bint(u3_noun* ops, u3_noun hif, u3_noun nef, c3_o los_o, c3_o tel_o)
             ++tot_w; _n_emit(ops, TOSS);
             tot_w += _n_comp(ops, nef, los_o, tel_o);
           } break;
-          case c3__near:
+          case c3__nara:
           case c3__hela:
           case c3__bout: {
             u3_noun fen = u3_nul;
@@ -1687,20 +1687,6 @@ u3n_find(u3_noun key, u3_noun fol)
   return pog_p;
 }
 
-/* TODO:
- *   - DONE: move slog tracing functions to trace.h/trace.c
- *   - DONE: implement hints for near and full trace
- *   - clean up style of docs etc
- *   - add a test for each hint to the hoon test suite
- *      - make it a test series of its own
- *      - is there a hoon test set for jets/hints/vere?
- *      - maybe in dir run or dir bug ...
- *   - submit a PR
- *   - ask world about pretty after pr merge
- *   - BONUS: setup home-manager with my new nix files
- */
-
-
 /* _n_hilt_fore(): literal (atomic) dynamic hint, before formula evaluation.
 **            hin: [hint-atom, formula]. TRANSFER
 **            bus: subject. RETAIN
@@ -1716,15 +1702,11 @@ _n_hilt_fore(u3_noun hin, u3_noun bus, u3_noun* out)
     u3_atom now = u3i_chub(u3t_trace_time());
     *out = u3i_cell(u3h(hin), now);
   }
-  else if ( c3__near == u3h(hin) ) {
-    // this will run BEFORE calling the wrapped code
-    // thus it prints a trace UPTO the call site
+  else if ( c3__nara == u3h(hin) ) {
     near_trace(0);
     *out = u3_nul;
   }
   else if ( c3__hela == u3h(hin) ) {
-    // this will run BEFORE calling the wrapped code
-    // thus it prints a trace UPTO the call site
     full_trace(0);
     *out = u3_nul;
   }
@@ -1752,7 +1734,7 @@ _n_hilt_hind(u3_noun tok, u3_noun pro)
     u3z(delta);
   }
   else if ( (c3y == u3r_cell(tok, &p_tok, &q_tok)) &&
-      ((c3__near == p_tok) || (c3__hela == p_tok))
+      ((c3__nara == p_tok) || (c3__hela == p_tok))
   ) {
     // DO NOTHING
   }
@@ -1775,7 +1757,7 @@ _n_hilt_hind(u3_noun tok, u3_noun pro)
 static c3_o
 _n_hint_fore(u3_cell hin, u3_noun bus, u3_noun* clu)
 {
-  if ( c3__bout == u3h(hin) || c3__near == u3h(hin) || c3__hela == u3h(hin) ) {
+  if ( c3__bout == u3h(hin) || c3__nara == u3h(hin) || c3__hela == u3h(hin) ) {
     u3_atom now = u3i_chub(u3t_trace_time());
     *clu = u3i_trel(u3h(hin), *clu, now);
   }
@@ -1818,7 +1800,7 @@ _n_hint_hind(u3_noun tok, u3_noun pro)
     u3z(delta);
   }
   else if ( (c3y == u3r_trel(tok, &p_tok, &q_tok, &r_tok)) &&
-      ((c3__near == p_tok) || (c3__hela == p_tok))
+      ((c3__nara == p_tok) || (c3__hela == p_tok))
   ) {
     // unpack q_tok to get the priority integer and the tank
     // p_q_tok is the priority, q_q_tok is the tank we will work with
@@ -1835,7 +1817,7 @@ _n_hint_hind(u3_noun tok, u3_noun pro)
     // send this to ut3_slog so that it can be logged out
     c3_l pri_l = c3y == u3a_is_cat(p_q_tok) ? p_q_tok : 0;
     dynamic_header(pri_l, u3i_string(str_c), u3k(q_q_tok));
-    if (c3__near == p_tok) {
+    if (c3__nara == p_tok) {
       near_trace(pri_l);
     }
     else {

pkg/urbit/noun/trace.c

@@ -627,9 +627,6 @@ slog_trace
   u3_noun ton = u3dc("mook", 2, u3kb_flop(tax));
   u3_noun lit = u3t(ton);
 
-  // TODO: we need to clean the means in the stack where we add
-  //       "call: failed", and "[ %gall-call-failed"
-
   // print the stack one stack item at a time
   while ( u3_nul != lit ) {
     u3t_slog(u3nc(pri_l, u3k(u3h(lit)) ));
@@ -658,14 +655,6 @@ near_trace(c3_l pri_l)
 void
 full_trace(c3_l pri_l)
 {
-  /* Goals:
-   * 01. DONE: print lines in the correct order
-   * 02. print only what we must per line, since we can see the whole stack
-   * 03. emphasize which clause in the last block led to the call of the next block?
-   * 04. emphasize virtualization changes
-   * 05. make the visual xp pretty, clear, and informative
-   */
-
   // rod_u protects us from mutating the global state
   u3_road* rod_u = u3R;
 
@@ -676,7 +665,6 @@ full_trace(c3_l pri_l)
   while ( &(u3H->rod_u) != rod_u ) {
     // ... point at the next road and append its stack to tax
     rod_u = u3tn(u3_road, rod_u->par_p);
-    // TODO: we can insert another mean or spot between tax, u3k(..
     tax = u3kb_weld(tax, u3k(rod_u->bug.tax));
   }