@@ -293,91 +293,45 @@ will send an ack packet directly to `~bacbel-tagfeb`. Communication between the
293293two ships will now be direct until one of them changes their IP address, port, or networking keys.
294294
295295
296−## A typical successful Ames exchange
297−
298−In this section we follow along a typical Ames interaction at a fairly detailed
299−level. This interaction can be summarized as Ship A making a request (called a
300−`%plea`) to Ship B to perform some task, and Ship B performing the requested
301−task and returning a few responses (called `%boon`s). For pedagogical reasons we
302−will assume that everything in this journey happens as it ought to - no crashes,
303−dropped packets, adversaries, etc.
304−
305−### The scenario
306−
307−While our story is generic and is roughly how every Ames interaction works, we
308−will be using `publish` as an example. Our story is summarized as follows.
309−
310−`~bacbel-tagfeb` is running the Gall app Publish and would like to subscribe to a public notebook
311−called `recipes` held on `~worwel-sipnum`. `~worwel` accepts the
312−request to subscribe from `~bacbel` and sends `~bacbel` each of the already
313−existing posts on her `recipes` notebook.
314−
315−### Stages
316−
317−We break our story into several stages, each of which will be detailed in its
318−own section.
319−
320−1. `~bacbel`'s Publish app initiates a request to subscribe to `~worwel`'s `recipes`
321− notebook.
322−2. `~bacbel`'s Gall receives the subscription request and packages it up as a `%plea` which
323− is forwarded to `~bacbel`'s Ames.
324−3. `~bacbel`'s Ames opens a new flow with `~worwel-sipnum` and sends the `%plea`
325− along it.
326−4. The `%plea` is turned into a message. `~bacbel`'s King now confirms that the message is
327− a valid Ames message. It is then added to the queue of messages to be sent.
328−5. The message arrives at the front of the queue and is broken into packets,
329− each of which is encrypted (or are they encrypted right before they are sent?)
330−6. `~bacbel`'s King encapsulates the packets in UDP wrappers, which it then
331− passes to its Ames I/O submodule.
332−7. Each UDP packet is sent to the IP address and port number for `~worwel`
333− previously known to `~bacbel` (how does it know this?)
334−8. `~worwel`'s King receives each packet, confirms that they are Ames packets, and hands them to `~worwel`'s Serf to be
335− unencrypted.
336−9. After each packet is received and successfully unencrypted, `~worwel`'s
337− Ames returns a packet-level ack to `~bacbel` along the same flow that the
338− packets came on.
339−10. Once all packets for the message have been received and acked by `~worwel`'s
340− Ames, it reconstructs the packets into the Ames message containing `~bacbel`'s `%plea`.
341−11. `~worwel`'s Ames returns a message-level ack as a `%boon` to `~bacbel`.
342−12. `~worwel`'s Ames passes the `%plea` to `~worwel`'s Gall.
343−13. `~worwel`'s Gall unwraps the `%plea` and finds that it is a `%poke` to
344− Publish, and hands it to Publish.
345−14. `~worwel`'s Publish sees that the `%poke` is a `%watch` `task` from
346− `~bacbel` to subscribe to the `recipes` notebook. It adds the subscription
347− to its state.
348−15. A `%watch-ack` is returned as a `%boon`?
349−16. `~worwel`'s Publish sends a `%watch-ack` to `~worwel`'s Ames, which is then converted
350− into a `%boon`s and returned to `~bacbel`.
351−17. `~bacbel` acks the `%boon`.
352−
353−Refer to timluc's Gall guide's `poke.md` for more info on subscription dataflows
354−
355−#### Initial Request
356−
357−
358−
359−`[%pass /subscription/path %agent [~worwel-sipnum publish] [%watch /path/to/recipes]]`
360−
361−
362−#### Flows
363−
364−Recall that a flow contains a bidirectional totally ordered sequence of messages
365−between the Ames vane of two ships. It is polarized in the sense that one ship
366−only sends `%plea`s and (n)acks, called the forward flow, and the other ship
367−only returns `%boon`s (which includes message-level (n)acks) and packet-level
368−acks, called the backwards flow. Note that while messages are totally ordered,
369−packets are not, and furthermore acks/nacks are not considered to be messages.
370−
371−So packets within a message, and acks acknowledging those packets, may be
372−received in any order. However, the next message will not be released from the queue until
373−each packet has been acked and the entire message has been (n)acked as well.
374−
375−Flow 1:
376−`%plea`s to `~worwel-sipnum` (forward flow)
377−1. 3 packets encoding a `%watch /path/to/recipes` at `publish`
378−
379−`%boon`s to `~bacbel-tagfeb` (backward flow)
380−1. 3 packet level acks
381−2. 1 `%done` message level ack
382−3. 1 `%watch-ack` as a `%boon`
296+## The Serf and the King
297+
298+Urbit's functionality is split between the two binaries `urbit-worker` (sometimes
299+called the Serf) and `urbit-king` (sometimes called the King). This division of
300+labor is currently not well-documented outside of the [Vere documents](@/docs/tutorials/vere/_index.md), but we summarize it here.
301+
302+In short, the Serf is the Nock runtime and so keeps track of the current state
303+of Arvo as a Nock noun and updates the state by `%poke`ing it with nouns, and
304+then informs the King of the new state. The King manages snapshots of the Arvo
305+state and handles I/O with Unix, among other things. The Serf only ever talks to
306+the King, while the King talks with both the Serf and Unix.
307+
308+### Ames
309+
310+The King has several submodules, one of them being an Ames I/O submodule. This
311+submodule is responsible for wrapping outgoing Ames packets as UDP packets, and
312+looking at incoming UDP packets handed to it by Unix to ensure that they are
313+valid Ames packets. It also maintains an incoming and outgoing packet queue.
314+
315+This division is summarized in the following diagram, describing how
316+`~bacbel-tagfeb` requests a subscription to the `recipes` notebook of
317+`~worwel-sipnum` in the Publish app.
318+
319+<div style="text-align:center">
320+<img src="https://media.urbit.org/docs/arvo/packet.png">
321+</div>
322+
323+Ames, as a part of Arvo, handles `+jam`ming, packetizing, encryption, and
324+forming Ames packets. Once it is ready to send an Ames packet, it `%give`s to
325+Unix a `%send` `gift` containing that packet. This will be a Nock noun
326+containing the `@tas` `%send` as well as the serialized packet.
327+
328+"Unix", in this case, is actually the King. The King receives the `%send`
329+instruction, wraps the packet contained within as a UDP packet, and queues the
330+UDP packet contained. Once it is time to send it (which will be determined by
331+congestion control), it will go ahead and forward the packet to Unix's
332+networking interface, at which point it is no longer controlled by any part of Urbit.
333+
334+Now the receiving King is handed a UDP packet by Unix. The King removes the UDP
335+wrapped and checks to see that it has received a valid Ames packet. If so, it
336+`+cue`s the payload and wraps it as a `%hear` `note` and passes it to the Serf.
383337