@@ -151,24 +151,69 @@ The body is of variable length and consists of three parts in this order:
151151 packet filtering for the interpreter.
152152
153153
154−## Journey of a Packet
154+## A typical successful Ames interaction
155+
156+In this section we follow along a typical Ames interaction at a fairly detailed
157+level. This interaction can be summarized as Ship A making a request (called a
158+`%plea`) to Ship B to perform some task, and Ship B performing the requested
159+task and returning a few responses (called `%boon`s). For pedagogical reasons we
160+will assume that everything in this journey happens as it ought to - no crashes,
161+dropped packets, adversaries, etc.
162+
163+### The scenario
164+
165+While our story is generic and is roughly how every Ames interaction works, we
166+will be using `publish` as an example. Our story is summarized as follows.
167+
168+`~bacbel-tagfeb` is running the Gall app Publish and would like to subscribe to a public notebook
169+called `recipes` held on `~worwel-sipnum`'s ship. `~worwel` accepts the
170+request to subscribe from `~bacbel` and sends `~bacbel` each of the already
171+existing posts on her `recipes` notebook.
172+
173+### Stages
174+
175+We break our story into several stages, each of which will be detailed in its
176+own section.
177+
178+1. `~bacbel`'s Publish app initiates a request to subscribe to `~worwel`'s `recipes`
179+ notebook.
180+2. `~bacbel`'s Gall receives the subscription request and packages it up as a `%plea` which
181+ is forwarded to `~bacbel`'s Ames.
182+3. `~bacbel`'s Ames opens a new flow with `~worwel-sipnum` and sends the `%plea`
183+ along it.
184+4. The `%plea` is turned into a message. `~bacbel`'s King now checks that the message is
185+ a valid Ames message. It is then added to the queue of messages to be sent.
186+5. The message arrives at the front of the queue and is broken into packets,
187+ each of which is encrypted (or are they encrypted right before they are sent?)
188+6. `~bacbel`'s King encapsulates the packets in UDP wrappers, which it then
189+ passes to its Ames I/O submodule.
190+7. Each UDP packet is sent to the IP address and port number for `~worwel`
191+ previously known to `~bacbel`.
192+8. `~worwel`'s King receives each packet and hands it to `~worwel`'s serf to be
193+ unencrypted.
194+9. After each packet is received and successfully unencrypted (?), `~worwel`'s
195+ Ames returns a packet-level ack to `~bacbel` along the same flow that the
196+ packets came on.
197+10. Once all packets for the message have been received and acked by `~worwel`'s
198+ Ames, it reconstructs the packets into the Ames message containing `~bacbel`'s `%plea`.
199+11. `~worwel`'s Ames passes the `%plea` to `~worwel`'s Gall.
200+12. `~worwel`'s Gall unwraps the `%plea` and finds that it is a `%poke` to
201+ Publish, and hands it to Publish.
202+13. `~worwel`'s Publish sees that the `%poke` is a `%watch` `task` from
203+ `~bacbel` to subscribe to the `recipes` notebook. It adds the subscription
204+ to its state.
205+14. A message level ack is sent from ??? along the same flow that the `%plea`
206+ was sent, informing `~bacbel` that the subscription was successful.
207+15. `~worwel`'s Publish sends %??? to `~worwel`'s Ames, which are then converted
208+ into `%boon`s and returned to `~bacbel`, etc.
209+
210+Refer to timluc's Gall guide's `poke.md` for more info on subscription dataflows
211+
212+#### Initial Request
213+
214+`[%pass /subscription/path %agent [~worwel-sipnum publish] [%watch /path/to/recipes]]`
155215
156−In this section we follow a packet through its entire journey, originating from
157−the Ames vane of ship A and ending in the Ames vane of ship B.
158216
159−This journey is broken into several stages:
160217
161−1. Ames receives a `%plea` note.
162−1.5 Does encryption happen here?
163−2. Serf A gives the note to King A (in what form? does it jam the payload?)k
164−3. King A checks that it is a valid Ames packet and wraps the Ames packet in a UDP packet (what does this look like?) and
165− give it to its Ames I/O submodule to send
166−4. UDP packet is sent to the receiving IP address (how is this determined? along
167− some port?)
168−5. King B receives a UDP packet on socket ? via the Ames submodule. It checks
169− that it is a valid Ames packet
170218
171219
172−A `%plea` `note` is given by `[vane=@tas =path payload=*]`, where
173−`vane` is the destination vane on the remote ship, `path` is the internal
174−route on the receiving ship `payload` is the semantic message content.