claude is gud

1 files changed, 1571 insertions, 0 deletions

diff --git a/vere/doc/spec/u3.md b/vere/doc/spec/u3.md
new file mode 100644
index 0000000..32ce9e8
--- /dev/null
+++ b/vere/doc/spec/u3.md
@@ -0,0 +1,1571 @@
+# u3: noun processing in C.
+
+`u3` is the C library that makes Urbit work.  If it wasn't called
+`u3`, it might be called `libnoun` - it's a library for making
+and storing nouns.
+
+What's a noun?  A noun is either a cell or an atom.  A cell is an
+ordered pair of any two nouns.  An atom is an unsigned integer of
+any size.
+
+To the C programmer, this is not a terribly complicated data
+structure, so why do you need a library for it?
+
+One: nouns have a well-defined computation kernel, Nock, whose
+spec fits on a page and gzips to 340 bytes.  But the only
+arithmetic operation in Nock is increment.  So it's nontrivial
+to compute both efficiently and correctly.
+
+Two: `u3` is designed to support "permanent computing," ie, a
+single-level store which is transparently snapshotted.  This
+implies a specialized memory-management model, etc, etc.
+
+(Does `u3` depend on the higher levels of Urbit, Arvo and Hoon?
+Yes and no.  `u3` expects you to load something shaped like an
+Arvo kernel, and use it as an event-processing function.  But you
+don't need to use this feature if you don't want, and your kernel
+doesn't have to be Arvo proper - just Arvo-compatible.  Think of
+`u3` as the BIOS and Arvo as the boot kernel.  And there are no
+dependencies at all between Hoon the language and `u3`.)
+
+## c3: C in Urbit
+
+Under `u3` is the simple `c3` layer, which is just how we write C
+in Urbit.
+
+When writing C in u3, please of course follow the conventions of
+the code around you as regards indentation, etc.  It's especially
+important that every function have a header comment, even if it
+says nothing interesting.
+
+But some of our idiosyncrasies go beyond convention.  Yes, we've
+done awful things to C. Here's what we did and why we did.
+
+### c3: integer types
+
+First, it's generally acknowledged that underspecified integer
+types are C's worst disaster.  C99 fixed this, but the `stdint`
+types are wordy and annoying.  We've replaced them with:
+
+    /* Good integers.
+    */
+      typedef uint64_t c3_d;  // double-word
+      typedef int64_t c3_ds;  // signed double-word
+      typedef uint32_t c3_w;  // word
+      typedef int32_t c3_ws;  // signed word
+      typedef uint16_t c3_s;  // short
+      typedef int16_t c3_ss;  // signed short
+      typedef uint8_t c3_y;   // byte
+      typedef int8_t c3_ys;   // signed byte
+      typedef uint8_t c3_b;   // bit
+
+      typedef uint8_t c3_t;   // boolean
+      typedef uint8_t c3_o;   // loobean
+      typedef uint8_t c3_g;   // 5-bit atom for a 32-bit log.
+      typedef uint32_t c3_l;  // little; 31-bit unsigned integer
+      typedef uint32_t c3_m;  // mote; also c3_l; LSB first a-z 4-char string.
+
+    /* Bad integers.
+    */
+      typedef char      c3_c; // does not match int8_t or uint8_t
+      typedef int       c3_i; // int - really bad
+      typedef uintptr_t c3_p; // pointer-length uint - really really bad
+      typedef intptr_t c3_ps; // pointer-length int - really really bad
+
+Some of these need explanation.  A loobean is a Nock boolean -
+Nock, for mysterious reasons, uses 0 as true (always say "yes")
+and 1 as false (always say "no").
+
+Nock and/or Hoon cannot tell the difference between a short atom
+and a long one, but at the `u3` level every atom under `2^31` is
+direct.  The `c3_l` type is useful to annotate this.  A `c3_m` is
+a *mote* - a string of up to 4 characters in a `c3_l`, least
+significant byte first.  A `c3_g` should be a 5-bit atom.  Of
+course, C cannot enforce these constraints, only document them.
+
+Use the "bad" - ie, poorly specified - integer types only when
+interfacing with external code that expects them.
+
+An enormous number of motes are defined in `i/c/motes.h`.  There
+is no reason to delete motes that aren't being used, or even to
+modularize the definitions.  Keep them alphabetical, though.
+
+### c3: variables and variable naming
+
+The C3 style uses Hoon style TLV variable names, with a quasi
+Hungarian syntax.  This is weird, but works really well, as long
+as what you're doing isn't hideously complicated.  (Then it works
+badly, but we shouldn't need anything hideous in u3.)
+
+A TLV variable name is a random pronounceable three-letter
+string, sometimes with some vague relationship to its meaning,
+but usually not.  Usually CVC (consonant-vowel-consonant) is a
+good choice.
+
+You should use TLVs much the way math people use Greek letters.
+The same concept should in general get the same name across
+different contexts.  When you're working in a given area, you'll
+tend to remember the binding from TLV to concept by sheer power
+of associative memory.  When you come back to it, it's not that
+hard to relearn.  And of course, when in doubt, comment it.
+
+Variables take pseudo-Hungarian suffixes, matching in general the
+suffix of the integer type:
+
+    c3_w wor_w;     //  32-bit word
+
+Unlike in standard Hungarian, there is no change for pointer
+variables.  C structure variables take a `_u` suffix.
+
+### c3: loobeans
+
+The code (from `defs.h`) tells the story:
+
+    #     define c3y      0
+    #     define c3n      1
+
+    #     define _(x)        (c3y == (x))
+    #     define __(x)       ((x) ? c3y : c3n)
+    #     define c3a(x, y)   __(_(x) && _(y))
+    #     define c3o(x, y)   __(_(x) || _(y))
+
+In short, use `_()` to turn a loobean into a boolean, `__` to go
+the other way.  Use `!` as usual, `c3y` for yes and `c3n` for no,
+`c3a` for and and `c3o` for or.
+
+## u3: land of nouns
+
+The division between `c3` and `u3` is that you could theoretically
+imagine using `c3` as just a generic C environment.  Anything to do
+with nouns is in `u3`.
+
+### u3: a map of the system
+
+There are two kinds of symbols in `u3`: regular and irregular.
+Regular symbols follow this pattern:
+
+    prefix    purpose                      .h         .c
+    -------------------------------------------------------
+    u3a_      allocation                   i/n/a.h    n/a.c
+    u3e_      persistence                  i/n/e.h    n/e.c
+    u3h_      hashtables                   i/n/h.h    n/h.c
+    u3i_      noun construction            i/n/i.h    n/i.c
+    u3j_      jet control                  i/n/j.h    n/j.c
+    u3m_      system management            i/n/m.h    n/m.c
+    u3n_      nock computation             i/n/n.h    n/n.c
+    u3r_      noun access (error returns)  i/n/r.h    n/r.c
+    u3t_      profiling                    i/n/t.h    n/t.c
+    u3v_      arvo                         i/n/v.h    n/v.c
+    u3x_      noun access (error crashes)  i/n/x.h    n/x.c
+    u3z_      memoization                  i/n/z.h    n/z.c
+    u3k[a-g]  jets (transfer, C args)      i/j/k.h    j/[a-g]/*.c
+    u3q[a-g]  jets (retain, C args)        i/j/q.h    j/[a-g]/*.c
+    u3w[a-g]  jets (retain, nock core)     i/j/w.h    j/[a-g]/*.c
+
+Irregular symbols always start with `u3` and obey no other rules.
+They're defined in `i/n/aliases.h`.  Finally, `i/all.h` includes
+all these headers (fast compilers, yay) and is all you need to
+program in `u3`.
+
+### u3: noun internals
+
+A noun is a `u3_noun` - currently defined as a 32-bit `c3_w`.
+
+If your `u3_noun` is less than `(1 << 31)`, it's a direct atom.
+Every unsigned integer between `0` and `0x7fffffff` inclusive is
+its own noun.
+
+If bit `31` is set in a `u3_noun` and bit `30` is `1` the noun
+is an indirect cell.  If bit `31` is set and bit `30` is `0` the
+noun is an indirect atom.  Bits `29` through `0` are a word
+pointer into the loom - see below.  The structures are:
+
+    typedef struct {
+      c3_w mug_w;
+      c3_w len_w;
+      c3_w buf_w[0];    //  actually [len_w]
+    } u3a_atom;
+
+    typedef struct {
+      c3_w    mug_w;
+      u3_noun hed;
+      u3_noun tel;
+    } u3a_cell;
+
+The only thing that should be mysterious here is `mug_w`, which
+is a 31-bit lazily computed nonzero short hash (FNV currently,
+soon Murmur3).  If `mug_w` is 0, the hash is not yet computed.
+We also hijack this field for various hacks, such as saving the
+new address of a noun when copying over.
+
+Also, the value `0xffffffff` is `u3_none`, which is never a valid
+noun.  Use the type `u3_weak` to express that a noun variable may
+be `u3_none`.
+
+### u3: reference counts
+
+The only really essential thing you need to know about `u3` is
+how to handle reference counts.  Everything else, you can skip
+and just get to work.
+
+u3 deals with reference-counted, immutable, acyclic nouns.
+Unfortunately, we are not Apple and can't build reference
+counting into your C compiler, so you need to count by hand.
+
+Every allocated noun (or any allocation object, because our
+allocator is general-purpose) contains a counter which counts the
+number of references to it - typically variables with type
+`u3_noun`.  When this counter goes to 0, the noun is freed.
+
+To tell `u3` that you've added a reference to a noun, call the
+function `u3a_gain()` or its shorthand `u3k()`.  (For your
+convenience, this function returns its argument.)  To tell `u3`
+that you've destroyed a reference, call `u3a_lose()` or `u3z()`.
+
+(If you screw up by decrementing the counter too much, `u3` will
+dump core in horrible ways.  If you screw up by incrementing it
+too much, `u3` will leak memory.  To check for memory leaks,
+set the `bug_o` flag in `u3e_boot()` - eg, run `vere` with `-g`.
+Memory leaks are difficult to debug - the best way to handle
+leaks is just to revert to a version that didn't have them, and
+look over your code again.)
+
+(You can gain or lose a direct atom.  It does nothing.)
+
+### u3: reference protocols
+
+*THIS IS THE MOST CRITICAL SECTION IN THE `u3` DOCUMENTATION.*
+
+The key question when calling a C function in a refcounted world
+is what the function will do to the noun refcounts - and, if the
+function returns a noun, what it does to the return.
+
+There are two semantic patterns, `transfer` and `retain`.  In
+`transfer` semantics, the caller "gives" a use count to the
+callee, which "gives back" any return.  For instance, if I have
+
+    {
+      u3_noun foo = u3i_string("foobar");
+      u3_noun bar;
+
+      bar = u3f_futz(foo);
+      [...]
+      u3z(bar);
+    }
+
+Suppose `u3f_futz()` has `transfer` semantics.  At `[...]`, my
+code holds one reference to `bar` and zero references to `foo` -
+which has been freed, unless it's part of `bar`.  My code now
+owns `bar` and gets to work with it until it's done, at which
+point a `u3z()` is required.
+
+On the other hand, if `u3f_futz()` has `retain` semantics, we
+need to write
+
+    {
+      u3_noun foo = u3i_string("foobar");
+      u3_noun bar;
+
+      bar = u3f_futz(foo);
+      [...]
+      u3z(foo);
+    }
+
+because calling `u3f_futz()` does not release our ownership of
+`foo`, which we have to free ourselves.
+
+But if we free `bar`, we are making a great mistake, because our
+reference to it is not in any way registered in the memory
+manager (which cannot track references in C variables, of
+course).  It is normal and healthy to have these uncounted
+C references, but they must be treated with care.
+
+The bottom line is that it's essential for the caller to  know
+the refcount semantics of any function which takes or returns a
+noun.  (In some unusual circumstances, different arguments or
+returns in one function may be handled differently.)
+
+Broadly speaking, as a design question, retain semantics are more
+appropriate for functions which inspect or query nouns.  For
+instance, `u3h()` (which takes the head of a noun) retains, so
+that we can traverse a noun tree without constantly incrementing
+and decrementing.
+
+Transfer semantics are more appropriate for functions which make
+nouns, which is obviously what most functions do.
+
+In general, though, in most places it's not worth thinking about
+what your function does.  There is a convention for it, which
+depends on where it is, not what it does.  Follow the convention.
+
+### u3: reference conventions
+
+The `u3` convention is that, unless otherwise specified, *all
+functions have transfer semantics* - with the exception of the
+prefixes: `u3r`, `u3x`, `u3z`, `u3q` and `u3w`.  Also, within
+jet directories `a` through `f` (but not `g`), internal functions
+retain (for historical reasons).
+
+If functions outside this set have retain semantics, they need to
+be commented, both in the `.h` and `.c` file, with `RETAIN` in
+all caps.  Yes, it's this important.
+
+### u3: system architecture
+
+If you just want to tinker with some existing code, it might be
+enough to understand the above.  If not, it's probably worth
+taking the time to look at `u3` as a whole.
+
+`u3` is designed to work as a persistent event processor.
+Logically, it computes a function of the form
+
+    f(event, old state) -> (actions, new state)
+
+Obviously almost any computing model - including, but not limited
+to, Urbit - can be defined in this form.  To create the illusion
+of a computer that never loses state and never fails, we:
+
+- log every event externally before it goes into u3
+- keep a single reference to a permanent state noun.
+- can abort any event without damaging the permanent state.
+- snapshot the permanent state periodically, and/or prune logs.
+
+### u3: the road model
+
+`u3` uses a memory design which I'm sure someone has invented
+somewhere before, because it's not very clever, but I've never
+seen it anywhere in particular.
+
+Every allocation starts with a solid block of memory, which `u3`
+calls the `loom`.  How do we allocate on the loom?  You're
+probably familiar with the Unix heap-stack design, in which the
+stack grows downward and the heap (malloc arena) grows upward:
+
+    0           brk                                          ffff
+    |   heap     |                                    stack    |
+    |------------#################################+++++++++++++|
+    |                                             |            |
+    0                                             sp         ffff
+
+A road is a normal heap-stack system, except that the heap
+and stack can point in *either direction*.  Therefore, inside
+a road, we can nest another road in the *opposite direction*.
+
+When the opposite road completes, its heap is left on top of
+the opposite heap's stack.  It's no more than the normal
+behavior of a stack machine for all subcomputations to push
+their results on the stack.
+
+The performance tradeoff of "leaping" - reversing directions in
+the road - is that if the outer computation wants to preserve the
+results of the inner one, not just use them for temporary
+purposes, it has to *copy them*.
+
+This is a trivial cost in some cases, a prohibitive cost in
+others.  The upside, of course, is that all garbage accrued
+in the inner computation is discarded at zero cost.
+
+The goal of the road system is the ability to *layer* memory
+models.  If you are allocating on a road, you have no idea
+how deep within a nested road system you are - in other words,
+you have no idea exactly how durable your result may be.
+But free space is never fragmented within a road.
+
+Roads do not reduce the generality or performance of a memory
+system, since even the most complex GC system can be nested
+within a road at no particular loss of performance - a road
+is just a block of memory.
+
+Each road (`u3a_road` to be exact) uses four pointers: `rut` is
+the bottom of the arena, `hat` the top of the arena, `mat` the
+bottom of the stack, `cap` the top of the stack.  (Bear in mind
+that the road "stack" is not actually used as the C function-call
+stack, though it probably should be.)
+
+A "north" road has the stack high and the heap low:
+
+    0           rut   hat                                    ffff
+    |            |     |                                       |
+    |~~~~~~~~~~~~-------##########################+++++++$~~~~~|
+    |                                             |      |     |
+    0                                            cap    mat  ffff
+
+A "south" road is the other way around:
+
+    0           mat   cap                                    ffff
+    |            |     |                                       |
+    |~~~~~~~~~~~~$++++++##########################--------~~~~~|
+    |                                             |      |     |
+    0                                            hat    rut  ffff
+
+Legend: `-` is durable storage (heap); `+` is temporary storage
+(stack); `~` is deep storage (immutable); `$` is the allocation
+frame; `#` is free memory.
+
+Pointer restrictions: pointers stored in `+` can point anywhere.
+Of course, pointing to `#` (free memory) would be a bug.
+Pointers in `-` can only point to `-` or `~`; pointers in `~`
+only point to `~`.
+
+To "leap" is to create a new inner road in the `###` free space.
+but in the reverse direction, so that when the inner road
+"falls" (terminates), its durable storage is left on the
+temporary storage of the outer road.
+
+`u3` keeps a global variable, `u3_Road` or its alias `u3R`, which
+points to the current road.  (If we ever run threads in inner
+roads - see below - this will become a thread-local variable.)
+Relative to `u3R`, `+` memory is called `junior` memory; `-`
+memory is `normal` memory; `~` is `senior` memory.
+
+### u3: explaining the road model
+
+But... why?
+
+We're now ready to understand why the road system works so
+logically with the event and persistence model.
+
+The key is that *we don't update refcounts in senior memory.*
+A pointer from an inner road to an outer road is not counted.
+Also, the outmost, or `surface` road, is the only part of the
+image that gets checkpointed.
+
+So the surface road contains the entire durable state of `u3`.
+When we process an event, or perform any kind of complicated or
+interesting calculation, *we process it in an inner road*.  If
+its results are saved, they need to be copied.
+
+Since processing in an inner road does not touch surface memory,
+(a) we can leave the surface road in a read-only state and not
+mark its pages dirty; (b) we can abort an inner calculation
+without screwing up the surface; and (c) because inner results
+are copied onto the surface, the surface doesn't get fragmented.
+
+All of (a), (b) and (c) are needed for checkpointing to be easy.
+It might be tractable otherwise, but easy is even better.
+
+Moreover, while the surface is most definitely single-threaded,
+we could easily run multiple threads in multiple inner roads
+(as long as the threads don't have pointers into each others'
+memory, which they obviously shouldn't).
+
+Moreover, in future, we'll experiment more with adding road
+control hints to the programmer's toolbox.  Reference counting is
+expensive.  We hypothesize that in many - if not most - cases,
+the programmer can identify procedural structures whose garbage
+should be discarded in one step by copying the results.  Then,
+within the procedure, we can switch the allocator into `sand`
+mode, and stop tracking references at all.
+
+### u3: rules for C programming
+
+There are two levels at which we program in C: (1) above the
+interpreter; (2) within the interpreter or jets.  These have
+separate rules which need to be respected.
+
+### u3: rules above the interpreter
+
+In its relations with Unix, Urbit follows a strict rule of "call
+me, I won't call you."  We do of course call Unix system calls,
+but only for the purpose of actually computing.
+
+Above Urbit, you are in a normal C/Unix programming environment
+and can call anything in or out of Urbit.  Note that when using
+`u3`, you're always on the surface road, which is not thread-safe
+by default.  Generally speaking, `u3` is designed to support
+event-oriented, single-threaded programming.
+
+If you need threads which create nouns, you could use
+`u3m_hate()` and `u3m_love()` to run these threads in subroads.
+You'd need to make the global road pointer, `u3R`, a thread-local
+variable instead.  This seems perfectly practical, but we haven't
+done it because we haven't needed to.
+
+### u3: rules within the interpreter
+
+Within the interpreter, your code can run either in the surface
+road or in a deep road.  You can test this by testing
+
+    (&u3H->rod_u == u3R)
+
+ie: does the pier's home road equal the current road pointer?
+
+Normally in this context you assume you're obeying the rules of
+running on an inner road, ie, "deep memory."  Remember, however,
+that the interpreter *can* run on surface memory - but anything
+you can do deep, you can do on the surface.  The converse is by
+no means the case.
+
+In deep memory, think of yourself as if in a signal handler.
+Your execution context is extremely fragile and may be terminated
+without warning or cleanup at any time (for instance, by ^C).
+
+For instance, you can't call `malloc` (or C++ `new`) in your C
+code, because you don't have the right to modify data structures
+at the global level, and will leave them in an inconsistent state
+if your inner road gets terminated.  (Instead, use our drop-in
+replacements, `u3a_malloc()`, `u3a_free()`, `u3a_realloc()`.)
+
+A good example is the different meaning of `u3_assert()` inside
+and outside the interpreter.  At either layer, you can use
+regular assert(), which will just kill your process.  On the
+surface, `u3_assert()` will just... kill your process.
+
+In deep execution, `u3_assert()` will issue an exception that
+queues an error event, complete with trace stack, on the Arvo
+event queue.   Let's see how this happens.
+
+### u3: exceptions
+
+You produce an exception with
+
+    /* u3m_bail(): bail out.  Does not return.
+    **
+    **  Bail motes:
+    **
+    **    %exit               ::  semantic failure
+    **    %evil               ::  bad crypto
+    **    %intr               ::  interrupt
+    **    %fail               ::  execution failure
+    **    %foul               ::  assert failure
+    **    %need               ::  network block
+    **    %meme               ::  out of memory
+    **    %time               ::  timed out
+    **    %oops               ::  assertion failure
+    */
+      c3_i
+      u3m_bail(c3_m how_m);
+
+Broadly speaking, there are two classes of exception: internal
+and external.  An external exception begins in a Unix signal
+handler.  An internal exception begins with a call to longjmp()
+on the main thread.
+
+There are also two kinds of exception: mild and severe.  An
+external exception is always severe.  An internal exception is
+normally mild, but some (like `c3__oops`, generated by
+`u3_assert()`) are severe.
+
+Either way, exceptions come with a stack trace.  The `u3` nock
+interpreter is instrumented to retain stack trace hints and
+produce them as a printable `(list tank)`.
+
+Mild exceptions are caught by the first virtualization layer and
+returned to the caller, following the behavior of the Nock
+virtualizer `++mock` (in `hoon.hoon`)
+
+Severe exceptions, or mild exceptions at the surface, terminate
+the entire execution stack at any depth and send the cumulative
+trace back to the `u3` caller.
+
+For instance, `vere` uses this trace to construct a `%crud`
+event, which conveys our trace back toward the Arvo context where
+it crashed.  This lets any UI component anywhere, even on a
+remote node, render the stacktrace as a consequence of the user's
+action - even if its its direct cause was (for instance) a Unix
+SIGINT or SIGALRM.
+
+### u3: C structures on the loom
+
+Normally, all data on the loom is nouns.  Sometimes we break this
+rule just a little, though - eg, in the `u3h` hashtables.
+
+To point to non-noun C structs on the loom, we use a `u3_post`,
+which is just a loom word offset.  A macro lets us declare this
+as if it was a pointer:
+
+    typedef c3_w       u3_post;
+    #define u3p(type)  u3_post
+
+Some may regard this as clever, others as pointless.  Anyway, use
+`u3to()` and `u3of()` to convert to and from pointers.
+
+When using C structs on the loom - generally a bad idea - make
+sure anything which could be on the surface road is structurally
+portable, eg, won't change size when the pointer size changes.
+(Note also: we consider little-endian, rightly or wrongly, to
+have won the endian wars.)
+
+## u3: API overview by prefix
+
+Let's run through the `u3` modules one by one.  All public
+functions are commented, but the comments may be cryptic.
+
+### u3m: main control
+
+To start `u3`, run
+
+    /* u3m_boot(): start the u3 system.
+    */
+      void
+      u3m_boot(c3_o nuu_o, c3_o bug_o, c3_c* dir_c);
+
+`nuu_o` is `c3y` (yes, `0`) if you're creating a new pier,
+`c3n` (no, `1`) if you're loading an existing one.  `bug_o`
+is `c3y` if you want to test the garbage-collector, `c3n`
+otherwise.  `dir_c` is the directory for the pier files.
+
+`u3m_boot()` expects an `urbit.pill` file to load the kernel
+from. This is specified with the -B commandline option.
+
+Any significant computation with nouns, certainly anything Turing
+complete, should be run (a) virtualized and (b) in an inner road.
+These are slightly different things, but at the highest level we
+bundle them together for your convenience, in `u3m_soft()`:
+
+    /* u3m_soft(): system soft wrapper.  unifies unix and nock errors.
+    **
+    **  Produces [%$ result] or [%error (list tank)].
+    */
+      u3_noun
+      u3m_soft(c3_w sec_w, u3_funk fun_f, u3_noun arg);
+
+`sec_w` is the number of seconds to time out the computation.
+`fun_f` is a C function accepting `arg`.
+
+The result of `u3m_soft()` is a cell whose head is an atom.  If
+the head is `%$` - ie, `0` - the tail is the result of
+`fun_f(arg)`.  Otherwise, the head is a `term` (an atom which is
+an LSB first string), and the tail is a `(list tank)` (a list of
+`tank` printables - see `++tank` in `hoon.hoon`).  Error terms
+should be the same as the exception terms above.
+
+If you're confident that your computation won't fail, you can
+use `u3m_soft_sure()`, `u3m_soft_slam()`, or `u3m_soft_nock()`
+for C functions, Hoon function calls, and Nock invocations.
+Caution - this returns just the result, and asserts globally.
+
+All the `u3m_soft` functions above work *only on the surface*.
+Within the surface, virtualize with `u3m_soft_run()`.  Note that
+this takes a `fly` (a namespace gate), thus activating the `11`
+super-operator in the nock virtualizer, `++mock`.  When actually
+using the `fly`, call `u3m_soft_esc()`.  Don't do either unless
+you know what you're doing!
+
+For descending into a subroad *without* Nock virtualization,
+use `u3m_hate()` and `u3m_love` respectively.  Hating enters
+a subroad; loving leaves it, copying out a product noun.
+
+Other miscellaneous tools in `u3m`: `u3m_file()` loads a Unix
+file as a Nock atom;  `u3m_water()` measures the boundaries of
+the loom in current use (ie, watermarks); and a variety of
+prettyprinting routines, none perfect, are available, mainly for
+debugging printfs: `u3m_pretty()`, `u3m_p()`, `u3m_tape()` and
+`u3m_wall()`.
+
+It's sometimes nice to run a mark-and-sweep garbage collector,
+`u3m_grab()`, which collects the world from a list of roots,
+and asserts if it finds any leaks or incorrect refcounts.  This
+tool is for debugging and long-term maintenance only; refcounts
+should never err.
+
+### u3j: jets
+
+The jet system, `u3j`, is what makes `u3` and `nock` in any sense
+a useful computing environment.  Except perhaps `u3a` (there is
+really no such thing as a trivial allocator, though `u3a` is
+dumber than most) - `u3j` is the most interesting code in `u3`.
+
+Let's consider the minor miracle of driver-to-battery binding
+which lets `u3j` work - and decrement not be `O(n)` - without
+violating the precisely defined semantics of pure Nock, *ever*.
+
+It's easy to assume that jets represent an architectural coupling
+between Hoon language semantics and Nock interpreter internals.
+Indeed such a coupling would be wholly wrongtious and un-Urbit.
+But the jet system is not Hoon-specific.  It is specific to nock
+runtime systems that use a design pattern we call a `core`.
+
+#### u3j: core structure
+
+A core is no more than a cell `[code data]`, in which a `code` is
+either a Nock formula or a cell of `code`s, and `data` is anything.
+In a proper core, the subject each formula expects is the core
+itself.
+
+Except for the arbitrary decision to make a core `[code data]`,
+(or as we sometimes say, `[battery payload]`), instead of `[data
+code]`, any high-level language transforming itself to Nock would
+use this design.
+
+So jets are in fact fully general.  Broadly speaking, the jet
+system works by matching a C *driver* to a battery.  When the
+battery is invoked with Nock operator `9`, it must be found in
+associative memory and linked to its driver.  Then we link the
+formula axis of the operation (`a` in `[9 a b]`) to a specific
+function in the driver.
+
+To validate this jet binding, we need to know two things.  One,
+we need to know the C function actually is a perfect semantic
+match for the Nock formula.  This can be developed with driver
+test flags, which work, and locked down with a secure formula
+hash in the driver, which we haven't bothered with just yet.
+(You could also try to develop a formal method for verifying
+that C functions and Nock formulas are equivalent, but this is
+a research problem for the future.)
+
+Two, we need to validate that the payload is appropriate for the
+battery.  We should note that jets are a Nock feature and have no
+reference to Hoon.  A driver which relies on the Hoon type system
+to only pair it with valid payloads is a broken driver, and
+breaks the Nock compliance of the system as a whole.  So don't.
+
+Now, a casual observer might look at `[battery payload]` and
+expect the simplest case of it to be `[formula subject]`.  That
+is: to execute a simple core whose battery is a single formula,
+we compute
+
+    nock(+.a -.a)
+
+Then, naturally, when we go from Hoon or a high-level language
+containing functions down to Nock, `[function arguments]` turns
+into `[formula subject]`.  This seems like an obvious design, and
+we mention it only because it is *completely wrong*.
+
+Rather, to execute a one-armed core like the above, we run
+
+    nock(a -.a)
+
+and the normal structure of a `gate`, which is simply Urbitese
+for "function," is:
+
+    [formula [sample context]]
+
+where `sample` is Urbitese for "arguments" - and `context`, any
+Lisper will at once recognize, is Urbitese for "environment."
+
+To `slam` or call the gate, we simply replace the default sample
+with the caller's data, then nock the formula on the entire gate.
+
+What's in the context?  Unlike in most dynamic languages, it is
+not some secret system-level bag of tricks.  Almost always it is
+another core.  This onion continues until at the bottom, there is
+an atomic constant, conventionally is the kernel version number.
+
+Thus a (highly desirable) `static` core is one of the form
+
+    [battery constant]
+    [battery static-core]
+
+ie, a solid stack of nested libraries without any dynamic data.
+The typical gate will thus be, for example,
+
+    [formula [sample [battery battery battery constant]]]
+
+but we would be most foolish to restrict the jet mechanism to
+cores of this particular structure.  We cannot constrain a
+payload to be `[sample static-core]`, or even `[sample core]`.
+Any such constraint would not be rich enough to handle Hoon,
+let alone other languages.
+
+#### u3j: jet state
+
+There are two fundamental rules of computer science: (1) every
+system is best understood through its state; (2) less state is
+better than more state.  Sadly, a pier has three different jet
+state systems: `cold`, `warm` and `hot`.  It needs all of them.
+
+Hot state is associated with this particular Unix process.  The
+persistent pier is portable not just between process and process,
+but machine and machine or OS and OS.  The set of jets loaded
+into a pier may itself change (in theory, though not in the
+present implementation) during the lifetime of the process.  Hot
+state is a pure C data structure.
+
+Cold state is associated with the logical execution history of
+the pier.  It consists entirely of nouns and ignores restarts.
+
+Warm state contains all dependencies between cold and hot
+state.  It consists of C structures allocated on the loom.
+
+Warm state is purely a function of cold and hot states, and
+we can wipe and regenerate it at any time.  On any restart where
+the hot state might have changed, we clear the warm state
+with `u3j_ream()`.
+
+There is only one hot state, the global jet dashboard
+`u3j_Dash` or `u3D` for short.  In the present implementation,
+u3D is a static structure not modified at runtime, except for
+numbering itself on process initialization.  This structure -
+which embeds function pointers to all the jets - is defined
+in `j/tree.c`.  The data structures:
+
+    /* u3j_harm: driver arm.
+    */
+      typedef struct _u3j_harm {
+        c3_c*               fcs_c;            //  `.axe` or name
+        u3_noun           (*fun_f)(u3_noun);  //  compute or 0 / semitransfer
+        c3_o                ice;              //  perfect (don't test)
+        c3_o                tot;              //  total (never punts)
+        c3_o                liv;              //  live (enabled)
+      } u3j_harm;
+
+    /* u3j_core: C core driver.
+    */
+      typedef struct _u3j_core {
+        c3_c*             cos_c;              //  control string
+        struct _u3j_harm* arm_u;              //  blank-terminated static list
+        struct _u3j_core* dev_u;              //  blank-terminated static list
+        struct _u3j_core* par_u;              //  dynamic parent pointer
+        c3_l              jax_l;              //  dynamic jet index
+      } u3j_core;
+
+    /* u3e_dash, u3_Dash, u3D: jet dashboard singleton
+    */
+      typedef struct _u3e_dash {
+        u3j_core* dev_u;                      //  null-terminated static list
+        c3_l      len_l;                      //  ray_u filled length
+        c3_l      all_l;                      //  ray_u allocated length
+        u3j_core* ray_u;                      //  dynamic driver array
+      } u3j_dash;
+
+Warm and cold state is *per road*.  In other words, as we nest
+roads, we also nest jet state.  The jet state in the road is:
+
+      struct {                                //  jet dashboard
+        u3p(u3h_root) har_p;                  //  warm state
+        u3_noun       das;                    //  cold state
+      } jed;
+
+In case you understand Hoon, `das` (cold state) is a `++dash`,
+and `har_p` (warm state) is a map from battery to `++calx`:
+
+    ++  bane  ,@tas                                 ::  battery name
+    ++  bash  ,@uvH                                 ::  label hash
+    ++  bosh  ,@uvH                                 ::  local battery hash
+    ++  batt  ,*                                    ::  battery
+    ++  calf                                        ::
+      $:  jax=,@ud                                  ::  hot core index
+          hap=(map ,@ud ,@ud)                       ::  axis/hot arm index
+          lab=path                                  ::  label as path
+          jit=*                                     ::  arbitrary data
+      ==                                            ::
+    ++  calx  (trel calf (pair bash cope) club)     ::  cached by battery
+    ++  clog  (pair cope (map batt club))           ::  identity record
+    ++  club  (pair corp (map term nock))           ::  battery pattern
+    ++  cope  (trel bane axis (each bash noun))     ::  core pattern
+    ++  core  ,*                                    ::  core
+    ++  corp  (each core batt)                      ::  parent or static
+    ++  dash  (map bash clog)                       ::  jet system
+
+The driver index `jax` in a `++calx` is an index into `ray_u` in the
+dashboard - ie, a pointer into hot state.  This is why the warm
+state has to be reset when we reload the pier in a new process.
+
+Why is jet state nested?  Nock of course is a functional system,
+so as we compute we don't explicitly create state.  Jet state is
+an exception to this principle (which works only because it can't
+be semantically detected from Nock/Hoon) - but it can't violate
+the fundamental rules of the allocation system.
+
+For instance, when we're on an inner road, we can't allocate on
+an outer road, or point from an outer road to an inner.  So if we
+learn something - like a mapping from battery to jet - in the
+inner road, we have to keep it in the inner road.
+
+Mitigating this problem, when we leave an inner road (with
+`u3m_love()`), we call `u3j_reap()` to promote jet information in
+the dying road.  Reaping promotes anything we've learned about
+any battery that either (a) already existed in the outer road, or
+(b) is being saved to the outer road.
+
+#### u3j: jet binding
+
+Jet binding starts with a `%fast` hint.  (In Hoon, this is
+produced by the runes `~%`, for the general case, or `~/`
+for simple functions.)  To bind a jet, execute a formula of the
+form:
+
+    [10 [%fast clue-formula] core-formula]
+
+`core-formula` assembles the core to be jet-propelled.
+`clue-formula` produces the hint information, or `++clue`
+above, which we want to annotate it with.
+
+A clue is a triple of name, parent, and hooks:
+
+    ++  clue  (trel chum nock (list (pair term nock)))
+
+The name, or `++chum`, has a bunch of historical structure which
+we don't need (cleaning these things up is tricky), but just gets
+flattened into a term.
+
+The parent axis is a nock formula, but always reduces to a simple
+axis, which is the address of this core's *parent*.  Consider
+again an ordinary gate
+
+    [formula [sample context]]
+
+Typically the `context` is itself a library core, which itself
+has a jet binding.  If so, the parent axis of this gate is `7`.
+
+If the parent is already bound - and the parent *must* be already
+bound, in this road or a road containing it - we can hook this core
+bottom-up into a tree hierarchy.  Normally the child core is
+produced by an arm of the parent core, so this is not a problem -
+we wouldn't have the child if we hadn't already made the parent.
+
+The clue also contains a list of *hooks*, named nock formulas on
+the core.  Usually these are arms, but they need not be.  The
+point is that we often want to call a core from C, in a situation
+where we have no type or other source information.  A common case
+of this is a complex system in which we're mixing functions which
+are jet-propelled with functions that aren't.
+
+In any case, all the information in the `%fast` hint goes to
+`u3j_mine()`, which registers the battery in cold state (`das` in
+`jed` in `u3R`), then warm state (`har_p` in `jed`).
+
+It's essential to understand that the `%fast` hint has to be,
+well, fast - because we apply it whenever we build a core.  For
+instance, if the core is a Hoon gate - a function - we will call
+`u3j_mine` every time the function is called.
+
+### u3j: the cold jet dashboard
+
+For even more fun, the jet tree is not actually a tree of
+batteries.  It's a tree of battery *labels*, where a label is
+an [axis term] path from the root of the tree.  (At the root,
+if the core pattern is always followed properly, is a core whose
+payload is an atomic constant, conventionally the Hoon version.)
+
+Under each of these labels, it's normal to have an arbitrary
+number of different Nock batteries (not just multiple copies
+of the same noun, a situation we *do* strive to avoid).  For
+instance, one might be compiled with debugging hints, one not.
+
+We might even have changed the semantics of the battery without
+changing the label - so long as those semantics don't invalidate
+any attached driver.
+
+et tree.  For instance, it's normal to have
+two equivalent Nock batteries at the same time in one pier: one
+battery compiled with debugging hints, one not.
+
+Rather, the jet tree is a semantic hierarchy.  The root of the
+hierarchy is a constant, by convention the Hoon kernel version
+because any normal jet-propelled core has, at the bottom of its
+onion of libraries, the standard kernel.  Thus if the core is
+
+    [foo-battery [bar-battery [moo-battery 164]]]
+
+we can reverse the nesting to construct a hierarchical core
+path.  The static core
+
+    164/moo/bar/foo
+
+extends the static core `164/moo/bar` by wrapping the `foo`
+battery (ie, in Hoon, `|%`) around it.  With the core above,
+you can compute `foo` stuff, `bar` stuff, and `moo` stuff.
+Rocket science, not.
+
+Not all cores are static, of course - they may contain live data,
+like the sample in a gate (ie, argument to a function).  Once
+again, it's important to remember that we track jet bindings not
+by the core, which may not be static, but by the battery, which
+is always static.
+
+(And if you're wondering how we can use a deep noun like a Nock
+formula or battery as a key in a key-value table, remember
+`mug_w`, the lazily computed short hash, in all boxed nouns.)
+
+In any case, `das`, the dashboard, is a map from `bash` to jet
+location record (`++clog`).  A `clog` in turn contains two kinds
+of information: the `++cope`, or per-location noun; and a map of
+batteries to a per-battery `++club`.
+
+The `cope` is a triple of `++bane` (battery name, right now just
+a `term`); `++axis`, the axis, within *this* core, of the parent;
+and `(each bash noun)`, which is either `[0 bash]` if the parent
+is another core, or `[1 noun]`, for the constant noun (like
+`164`) if there is no parent core.
+
+A `bash` is just the noun hash (`++sham`) of a `cope`, which
+uniquely expresses the battery's hierarchical location without
+depending on the actual formulas.
+
+The `club` contains a `++corp`, which we use to actually validate
+the core.  Obviously jet execution has to be perfectly compatible
+with Nock.  We search on the battery, but getting the battery
+right is not enough - a typical battery is dependent on its
+context.  For example, your jet-propelled library function is
+very likely to call `++dec` or other advanced kernel technology.
+If you've replaced the kernel in your context with something
+else, we need to detect this and not run the jet.
+
+There are two cases for a jet-propelled core - either the entire
+core is a static constant, or it isn't.  Hence the definition
+of `corp`:
+
+    ++  corp  (each core batt)                ::  parent or static
+
+Ie, a `corp` is `[0 core]` or `[1 batt]`.  If it's static -
+meaning that the jet only works with one specific core, ie, the
+parent axis of each location in the hierarchy is `3` - we can
+validate with a single comparison.  Otherwise, we have to recurse
+upward by checking the parent.
+
+Note that there is at present no way to force a jet to depend on
+static *data*.
+
+### u3j: the warm jet dashboard
+
+We don't use the cold state to match jets as we call them.  We
+use the cold state to register jets as we find them, and also to
+rebuild the warm state after the hot state is reset.
+
+What we actually use at runtime is the warm state, `jed->har_p`,
+which is a `u3h` (built-in hashtable), allocated on the loom,
+from battery to `++calx`.
+
+A `calx` is a triple of a `++calf`, a `[bash cope]` cell, and a
+`club`.  The latter two are all straight from cold state.
+
+The `calf` contains warm data dependent on hot state.  It's a
+quadruple: of `jax`, the hot driver index (in `ray_u` in
+`u3j_dash`); `hap`, a table from arm axis (ie, the axis of each
+formula within the battery) to driver arm index (into `arm_u` in
+`u3j_core`); `lab`, the complete label path; and  `jit`, any
+other dynamic data that may speed up execution.
+
+We construct `hap`, when we create the calx, by iterating through
+the arms registered in the `u3j_core`.  Note the way a `u3j_harm`
+declares itself, with the string `fcs_c` which can contain either
+an axis or a name.  Most jetted cores are of course gates, which
+have one formula at one axis within the core: `fcs_c` is `".3"`.
+
+But we do often have fast cores with more complex arm structure,
+and it would be sad to have to manage their axes by hand.  To use
+an `fcs_c` with a named arm, it's sufficient to make sure the
+name is bound to a formula `[0 axis]` in the hook table.
+
+`jit`, as its name suggests, is a stub where any sort of
+optimization data computed on battery registration might go.  To
+use it, fill in the `_cj_jit()` function.
+
+### u3j: the hot dashboard
+
+Now it should be easy to see how we actually invoke jets.  Every
+time we run a nock `9` instruction (pretty often, obviously), we
+have a core and an axis.  We pass these to `u3j_kick()`, which
+will try to execute them.
+
+Because nouns with a reference count of 1 are precious,
+`u3j_kick()` has a tricky reference control definition.  It
+reserves the right to return `u3_none` in the case where there is
+no driver, or the driver does not apply for this case; in this
+case, it retains argument `cor`.  If it succeeds, though, it
+transfers `cor`.
+
+`u3j_kick()` searches for the battery (always the head of the
+core, of course) in the hot dashboard.  If the battery is
+registered, it searches for the axis in `hap` in the `calx`.
+If it exists, the core matches a driver and the driver jets this
+arm.  If not, we return `u3_none`.
+
+Otherwise, we call `fun_f` in our `u3j_harm`.  This obeys the
+same protocol as `u3j_kick()`; it can refuse to function by
+returning `u3_none`, or consume the noun.
+
+Besides the actual function pointer `fun_f`, we have some flags
+in the `u3j_harm` which tell us how to call the arm function.
+
+If `ice` is yes (`&`, `0`), the jet is known to be perfect and we
+can just trust the product of `fun_f`.  Otherwise, we need to run
+*both* the Nock arm and `fun_f`, and compare their results.
+
+(Note that while executing the C side of this test, we have to
+set `ice` to yes; on the Nock side, we have to set `liv` to no.
+Otherwise, many non-exponential functions become exponential.
+When auto-testing jets in this way, the principle is that the
+test is on the outermost layer of recursion.)
+
+(Note also that anyone who multi-threads this execution
+environment has a slight locking problem with these flags if arm
+testing is multi-threaded.)
+
+If `tot` is yes, (`&`, `0`), the arm function is *total* and has
+to return properly (though it can still return *u3_none*).
+Otherwise, it is *partial* and can `u3_cm_bail()` out with
+c3__punt.  This feature has a cost: the jet runs in a subroad.
+
+Finally, if `liv` is no (`|`, 1), the jet is off and doesn't run.
+
+It should be easy to see how the tree of cores gets declared -
+precisely, in `j/dash.c`.  We declare the hierarchy as a tree
+of `u3j_core` structures, each of which comes with a static list
+of arms `arm_u` and sub-cores `dev_u`.
+
+In `u3j_boot()`, we traverse the hierarchy, fill in parent
+pointers `par_u`, and enumerate all `u3j_core` structures
+into a single flat array `u3j_dash.ray_u`.  Our hot state
+then appears ready for action.
+
+### u3j: jet functions
+
+At present, all drivers are compiled statically into `u3`.  This is
+not a long-term permanent solution or anything.  However, it will
+always be the case with a certain amount of core functionality.
+
+For instance, there are some jet functions that we need to call
+as part of loading the Arvo kernel - like `++cue` to unpack a
+noun from an atom.  And obviously it makes sense, when jets are
+significant enough to compile into `u3`, to export their symbols
+in headers and the linker.
+
+There are three interface prefixes for standard jet functions:
+`u3k`, `u3q`, and `u3w`.  All jets have `u3w` interfaces; most
+have `u3q`; some have `u3k`.  Of course the actual logic is
+shared.
+
+`u3w` interfaces use the same protocol as `fun_f` above: the
+caller passes the entire core, which is retained if the function
+returns `u3_none`, transferred otherwise.  Why?   Again, use
+counts of 1 are special and precious for performance hackers.
+
+`u3q` interfaces break the core into C arguments, *retain* noun
+arguments, and *transfer* noun returns.  `u3k` interfaces are the
+same, except with more use of `u3_none` and other simple C
+variations on the Hoon original, but *transfer* both arguments
+and returns.  Generally, `u3k` are most convenient for new code.
+
+Following `u3k/q/w` is `[a-f]`, corresponding to the 6 logical
+tiers of the kernel, or `g` for user-level jets.  Another letter
+is added for functions within subcores.  The filename, under
+`j/`, follows the tier and the function name.
+
+For instance, `++add` is `u3wa_add(cor)`, `u3qa_add(a, b)`, or
+`u3ka_add(a, b)`, in `j/a/add.c`.  `++get` in `++by` is
+`u3wdb_get(cor)`, `u3kdb_get(a, b)`, etc, in `j/d/by_get.c`.
+
+For historical reasons, all internal jet code in `j/[a-f]`
+*retains* noun arguments, and *transfers* noun results.  Please
+do not do this in new `g` jets!  The new standard protocol is to
+transfer both arguments and results.
+
+### u3a: allocation functions
+
+`u3a` allocates on the current road (u3R).  Its internal
+structures are uninteresting and typical of a naive allocator.
+
+The two most-used `u3a` functions are `u3a_gain()` to add a
+reference count,  and `u3a_lose()` to release one (and free the
+noun, if the use count is zero).  For convenience, `u3a_gain()`
+returns its argument.  The pair are generally abbreviated with
+the macros `u3k()` and `u3z()` respectively.
+
+Normally we create nouns through `u3i` functions, and don't call
+the `u3a` allocators directly.  But if you do:
+
+One, there are *two* sets of allocators: the word-aligned
+allocators and the fully-aligned (ie, malloc compatible)
+allocators.  For instance, on a typical OS X setup, malloc
+produces 16-byte aligned results - needed for some SSE
+instructions.
+
+These allocators are *not compatible*.  For 32-bit alignment
+as used in nouns, call
+
+    /* u3a_walloc(): allocate storage measured in words.
+    */
+      void*
+      u3a_walloc(c3_w len_w);
+
+    /* u3a_wfree(): free storage.
+    */
+      void
+      u3a_wfree(void* lag_v);
+
+    /* u3a_wealloc(): word realloc.
+    */
+      void*
+      u3a_wealloc(void* lag_v, c3_w len_w);
+
+For full alignment, call:
+
+    /* u3a_malloc(): aligned storage measured in bytes.
+    */
+      void*
+      u3a_malloc(size_t len_i);
+
+    /* u3a_realloc(): aligned realloc in bytes.
+    */
+      void*
+      u3a_realloc(void* lag_v, size_t len_i);
+
+    /* u3a_realloc2(): gmp-shaped realloc.
+    */
+      void*
+      u3a_realloc2(void* lag_v, size_t old_i, size_t new_i);
+
+    /* u3a_free(): free for aligned malloc.
+    */
+      void
+      u3a_free(void* tox_v);
+
+    /* u3a_free2(): gmp-shaped free.
+    */
+      void
+      u3a_free2(void* tox_v, size_t siz_i);
+
+There are also a set of special-purpose allocators for building
+atoms.  When building atoms, please remember that it's incorrect
+to have a high 0 word - the word length in the atom structure
+must be strictly correct.
+
+Of course, we don't always know how large our atom will be.
+Therefore, the standard way of building large atoms is to
+allocate a block of raw space with `u3a_slab()`, then chop off
+the end with `u3a_malt()` (which does the measuring itself)
+or `u3a_mint()` in case you've measured it yourself.
+
+Once again, *do not call `malloc()`* (or C++ `new`) within any
+code that may be run within a jet.  This will cause rare sporadic
+corruption when we interrupt execution within a `malloc()`.  We'd
+just override the symbol, but `libuv` uses `malloc()` across
+threads within its own synchronization primitives - for this to
+work with `u3a_malloc()`, we'd have to introduce our own locks on
+the surface-level road (which might be a viable solution).
+
+### u3n: nock execution
+
+The `u3n` routines execute Nock itself.  On the inside, they have
+a surprising resemblance to the spec proper (the only interesting
+detail is how we handle tail-call elimination) and are, as one
+would expect, quite slow.  (There is no such thing as a fast tree
+interpreter.)
+
+There is only one Nock, but there are lots of ways to call it.
+(Remember that all `u3n` functions *transfer* C arguments and
+returns.)
+
+The simplest interpreter, `u3n_nock_on(u3_noun bus, u3_noun fol)`
+invokes Nock on `bus` (the subject) and `fol` (the formula).
+(Why is it`[subject formula]`, not `[formula subject]`?  The same
+reason `0` is true and `1` is false.)
+
+A close relative is `u3n_slam_on(u3_noun gat, u3_noun sam)`,
+which slams a *gate* (`gat`) on a sample (`sam`).  (In a normal
+programming language which didn't talk funny and was retarded,
+`u3n_slam_on()` would call a function on an argument.)  We could
+write it most simply as:
+
+    u3_noun
+    u3n_slam_on(u3_noun gat, u3_noun sam)
+    {
+      u3_noun pro = u3n_nock_on
+                      (u3nc(u3k(u3h(gat)),
+                            u3nc(sam, u3k(u3t(u3t(gat))))),
+                       u3k(u3h(gat)));
+      u3z(gat);
+      return pro;
+    }
+
+Simpler is `u3n_kick_on(u3_noun gat)`, which slams a gate (or,
+more generally, a *trap* - because sample structure is not even
+needed here) without changing its sample:
+
+    u3_noun
+    u3n_kick_on(u3_noun gat, u3_noun sam)
+    {
+      return u3n_nock_on(gat, u3k(u3h(gat)));
+    }
+
+The `_on` functions in `u3n` are all defined as pure Nock.  But
+actually, even though we say we don't extend Nock, we do.  But we
+don't.  But we do.
+
+Note that `u3` has a well-developed error handling system -
+`u3m_bail()` to throw an exception, `u3m_soft_*` to catch one.
+But Nock has no exception model at all.  That's okay - all it
+means if that if an `_on` function bails, the exception is an
+exception in the caller.
+
+However, `u3`'s exception handling happens to match a convenient
+virtual super-Nock in `hoon.hoon`, the infamous `++mock`.  Of
+course, Nock is slow, and `mock` is Nock in Nock, so it is
+(logically) super-slow.  Then again, so is decrement.
+
+With the power of `u3`, we nest arbitrary layers of `mock`
+without any particular performance cost.  Moreover, we simply
+treat Nock proper as a special case of `mock`.  (More precisely,
+the internal VM loop is `++mink` and the error compiler is
+`++mook`.  But we call the whole sandbox system `mock`.)
+
+The nice thing about `mock` functions is that (by executing
+within `u3m_soft_run()`, which as you may recall uses a nested
+road) they provide both exceptions and the namespace operator -
+`.^` in Hoon, which becomes operator `11` in `mock`.
+
+`11` requires a namespace function, or `fly`, which produces a
+`++unit` - `~` (`0`) for no binding, or `[0 value]`.  The sample
+to a `fly` is a `++path`, just a list of text `span`.
+
+`mock` functions produce a `++toon`.  Fully elaborated:
+
+    ++  noun  ,*                                      ::  any noun
+    ++  path  (list ,@ta)                             ::  namespace path
+    ++  span  ,@ta                                    ::  text-atom (ASCII)
+    ++  toon  $%  [%0 p=noun]                         ::  success
+                  [%1 p=(list path)]                  ::  blocking paths
+                  [%2 p=(list tank)]                  ::  stack trace
+              ==                                      ::
+    ++  tank                                          ::  printable
+              $%  [%leaf p=tape]                      ::  flat text
+                  $:  %palm                           ::  backstep list
+                      p=[p=tape q=tape r=tape s=tape] ::  mid cap open close
+                      q=(list tank)                   ::  contents
+                  ==                                  ::
+                  $:  %rose                           ::  straight list
+                      p=[p=tape q=tape r=tape]        ::  mid open close
+                      q=(list tank)                   ::  contents
+                  ==                                  ::
+              ==
+
+(Note that `tank` is overdesigned and due for replacement.)
+
+What does a `toon` mean?  Either your computation succeded (`[0
+noun]`, or could not finish because it blocked on one or more
+global paths (`[1 (list path)]`), or it exited with a stack trace
+(`[2 (list tank)]`).
+
+Note that of all the `u3` exceptions, only `%exit` is produced
+deterministically by the Nock definition.  Therefore, only
+`%exit` produces a `2` result.  Any other argument to
+`u3m_bail()` will unwind the virtualization stack all the way to
+the top - or to be more exact, to `u3m_soft_top()`.
+
+In any case, the simplest `mock` functions are `u3n_nock_un()`
+and `u3n_slam_un()`.  These provide exception control without
+any namespace change, as you can see by the code:
+
+    /* u3n_nock_un(): produce .*(bus fol), as ++toon.
+    */
+    u3_noun
+    u3n_nock_un(u3_noun bus, u3_noun fol)
+    {
+      u3_noun fly = u3nt(u3nt(11, 0, 6), 0, 0);  //  |=(a=* .^(a))
+
+      return u3n_nock_in(fly, bus, fol);
+    }
+
+    /* u3n_slam_un(): produce (gat sam), as ++toon.
+    */
+    u3_noun
+    u3n_slam_un(u3_noun gat, u3_noun sam)
+    {
+      u3_noun fly = u3nt(u3nt(11, 0, 6), 0, 0);  //  |=(a=* .^(a))
+
+      return u3n_slam_in(fly, gat, sam);
+    }
+
+The `fly` is added as the first argument to `u3n_nock_in()` and
+`u3n_slam_in()`.  Of course, logically, `fly` executes in the
+caller's exception layer.  (Maintaining this illusion is slightly
+nontrivial.)  Finally, `u3n_nock_an()` is a sandbox with a null
+namespace.
+
+### u3e: persistence
+
+The only `u3e` function you should need to call is `u3e_save()`,
+which saves the loom.  As it can be restored on any platform,
+please make sure you don't have any state in the loom that is
+bound to your process or architecture - except for exceptions
+like the warm jet state, which is actively purged on reboot.
+
+### u3r: reading nouns (weak)
+
+As befits accessors they don't make anything, `u3r` noun reading
+functions always retain their arguments and their returns.  They
+never bail; rather, when they don't work, they return a `u3_weak`
+result.
+
+Most of these functions are straightforward and do only what
+their comments say.  A few are interesting enough to discuss.
+
+`u3r_at()` is the familiar tree fragment function, `/` from the
+Nock spec.  For taking complex nouns apart, `u3r_mean()` is a
+relatively funky way of deconstructing nouns with a varargs list
+of `axis`, `u3_noun *`.  For cells, triples, etc, decompose with
+`u3r_cell()`, `u3r_trel()`, etc.  For the tagged equivalents, use
+`u3r_pq()` and friends.
+
+`u3r_sing(u3_noun a, u3_noun b)` (true if `a` and `b` are a
+*single* noun) are interesting because it uses mugs to help it
+out.  Clearly, different nouns may have the same mug, but the
+same nouns cannot have a different mug.  It's important to
+understand the performance characteristics of `u3r_sing()`:
+the worst possible case is a comparison of duplicate nouns,
+which have the same value but were created separately.  In this
+case, the tree is traversed
+
+`u3r_sung()` is a deeply funky and frightening version of
+`u3r_sing()` that unifies pointers to the duplicate nouns it
+finds, freeing the second copy.  Obviously, do not use
+`u3r_sung()` when you have live, but not reference counted, noun
+references from C - if they match a noun with a refcount of 1
+that gets freed, bad things happen.
+
+It's important to remember that `u3r_mug()`, which produces a
+31-bit, nonzero insecure hash, uses the `mug_w` slot in any boxed
+noun as a lazy cache.  There are a number of variants of
+`u3r_mug()` that can get you out of building unneeded nouns.
+
+### u3x: reading nouns (bail)
+
+`u3x` functions are like `u3r` functions, but instead of
+returning `u3_none` when (for instance) we try to take the head
+of an atom, they bail with `%exit`.  In other words, they do what
+the same operation would do in Nock.
+
+### u3h: hash tables.
+
+We can of course use the Hoon `map` structure as an associative
+array.  This is a balanced treap and reasonably fast.  However,
+it's considerably inferior to a custom structure like an HAMT
+(hash array-mapped trie).  We use `u3_post` to allocate HAMT
+structures on the loom.
+
+(Our HAMT implements the classic Bagwell algorithm which depends
+on the `gcc` standard directive `__builtin_popcount()`.  On a CPU
+which doesn't support popcount or an equivalent instruction, some
+other design would probably be preferable.)
+
+There's no particular rocket science in the API. `u3h_new()`
+creates a hashtable; `u3h_free()` destroys one; `u3h_put()`
+inserts, `u3h_get()` retrieves.  You can transform values in a
+hashtable with `u3h_walk()`.
+
+The only funky function is `u3h_gut()`, which unifies keys with
+`u3r_sung()`.  As with all cases of `u3r_sung()`, this must be
+used with extreme caution.
+
+### u3z: memoization
+
+Connected to the `~+` rune in Hoon, via the Nock `%memo` hint,
+the memoization facility is a general-purpose cache.
+
+(It's also used for partial memoization - a feature that'll
+probably be removed, in which conservative worklist algorithms
+(which would otherwise be exponential) memoize everything in the
+subject *except* the worklist.  This is used heavily in the Hoon
+compiler jets (j/f/*.c).  Unfortunately, it's probably not
+possible to make this work perfectly in that it can't be abused
+to violate Nock, so we'll probably remove it at a later date,
+instead making `++ut` keep its own monadic cache.)
+
+Each `u3z` function comes with a `c3_m` mote which disambiguates
+the function mapping key to value.  For Nock itself, use 0.  For
+extra speed, small tuples are split out in C; thus, find with
+
+    u3_weak u3z_find(c3_m, u3_noun);
+    u3_weak u3z_find_2(c3_m, u3_noun, u3_noun);
+    u3_weak u3z_find_3(c3_m, u3_noun, u3_noun, u3_noun);
+    u3_weak u3z_find_4(c3_m, u3_noun, u3_noun, u3_noun, u3_noun);
+
+and save with
+
+    u3_noun u3z_save(c3_m, u3_noun, u3_noun);
+    u3_noun u3z_save_2(c3_m, u3_noun, u3_noun, u3_noun);
+    u3_noun u3z_save_3(c3_m, u3_noun, u3_noun, u3_noun, u3_noun);
+    u3_noun u3z_save_4(c3_m, u3_noun, u3_noun, u3_noun, u3_noun, u3_noun);
+
+where the value is the last argument.  To eliminate duplicate
+nouns, there is also
+
+    u3_noun
+    u3z_uniq(u3_noun);
+
+`u3z` functions retain keys and transfer values.
+
+The `u3z` cache, built on `u3h` hashes, is part of the current
+road, and goes away when it goes away.  (In future, we may wish
+to promote keys/values which outlive the road, as we do with jet
+state.)  There is no cache reclamation at present, so be careful.
+
+### u3t: tracing and profiling.
+
+TBD.
+
+### u3v: the Arvo kernel
+
+An Arvo kernel - or at least, a core that compiles with the Arvo
+interface - is part of the global `u3` state.  What is an Arvo
+core?  Slightly pseudocoded:
+
+    ++  arvo
+      |%
+      ++  come  |=  [yen=@ ova=(list ovum) nyf=pone]  ::  11
+                ^-  [(list ovum) _+>]
+                !!
+      ++  keep  |=  [now=@da hap=path]                ::  4
+                ^-  (unit ,@da)
+                !!
+      ++  load  |=  [yen=@ ova=(list ovum) nyf=pane]  ::  86
+                ^-  [(list ovum) _+>]
+                !!
+      ++  peek  |=  [now=@da path]                    ::  87
+                ^-  (unit)
+                !!
+      ++  poke  |=  [now=@da ovo=ovum]                ::  42
+                ^-  [(list ovum) _+>]
+                !!
+      ++  wish  |=  txt=@ta                           ::  20
+                ^-  *
+                !!
+      --
+    ++  card  ,[p=@tas q=*]                           ::  typeless card
+    ++  ovum  ,[p=wire q=card]                        ::  Arvo event
+    ++  wire  path                                    ::  event cause
+
+This is the Arvo ABI in a very real sense.  Arvo is a core with
+these six arms.  To use these arms, we hardcode the axis of the
+formula (`11`, `4`, `86`, etc) into the C code that calls Arvo,
+because otherwise we'd need type metadata - which we can get, by
+calling Arvo.
+
+It's important to understand the Arvo event/action structure, or
+`++ovum`.  An `ovum` is a `card`, which is any `[term noun]`
+cell, and a `++wire`, a `path` which indicates the location of
+the event.  At the Unix level, the `wire` corresponds to a system
+module or context.  For input events, this is the module that
+caused the event; for output actions, it's the module that
+performs the action.
+
+`++poke` sends Arvo an event `ovum`, producing a cell of action
+ova and a new Arvo core.
+
+`++peek` dereferences the Arvo namespace.  It takes a date and a
+key, and produces `~` (`0`) or `[~ value]`.
+
+`++keep` asks Arvo the next time it wants to be woken up, for the
+given `wire`.  (This input will probably be eliminated in favor
+of a single global timer.)
+
+`++wish` compiles a string of Hoon source.  While just a
+convenience, it's a very convenient convenience.
+
+`++come` and `++load` are used by Arvo to reset itself (more
+precisely, to shift the Arvo state from an old kernel to a new
+one); there is no need to call them from C.
+
+Now that we understand the Arvo kernel interface, let's look at
+the `u3v` API.  As usual, all the functions in `u3v` are
+commented, but unfortunately it's hard to describe this API as
+clean at present.  The problem is that `u3v` remains design
+coupled to the old `vere` event handling code written for `u2`.
+But let's describe the functions you should be calling, assuming
+you're not writing the next event system.  There are only two.
+
+`u3v_wish(str_c)` wraps the `++wish` functionality in a cache
+(which is read-only unless you're on the surface road).
+
+`u3v_do()` uses `wish` to provide a convenient interface for
+calling Hoon kernel functions by name.  Even more conveniently,
+we tend to call `u3v_do()` with these convenient aliases:
+
+    #define  u3do(txt_c, arg)         u3v_do(txt_c, arg)
+    #define  u3dc(txt_c, a, b)        u3v_do(txt_c, u3nc(a, b))
+    #define  u3dt(txt_c, a, b, c)     u3v_do(txt_c, u3nt(a, b, c))
+    #define  u3dq(txt_c, a, b, c, d)  u3v_do(txt_c, u3nt(a, b, c, d))
+