@@ -120,7 +120,7 @@ Debug output can be adjusted using `%sift` and `%spew` `$task`'s.
120120Ames datagram packets are handled as nouns internally by Arvo but as serial data
121121by Unix. In this section we describe how packets are formed, serialized, and relayed.
122122
123−### Serial format
123+### Packet format
124124
125125There is a 32-bit header followed by a variable width body.
126126
@@ -161,7 +161,7 @@ required to send the message. To do this, it first `+jam`s the
161161message, producing an atom. Ames checks how large the atom is, and if it is
162162bigger than a kilobyte it will split it into packets whose payloads are 1 kB or
163163less. It then numbers each one - this is message 17, packet 12, this is message
164−17, packet 13, etc, so that when the receiver receives these packets it knows
164+17, packet 13, etc., so that when the receiver receives these packets it knows
165165which number they are. Finally it encrypts each individual packet and enqueues
166166them to be sent along their stated flow.
167167
@@ -170,24 +170,21 @@ for reconstruction, and also packets may get lost. So Ames does transmission
170170control (the TC in TCP) to solve this problem. It makes sure that all packets
171171eventually get through, and when the other side gets them it can put them in the
172172correct order. If Ames doesn't get an ack on a packet then it will resend it
173−until it does. The timing on resending packets is called congestion control and
174−works in the same fashion as TCP, namely exponential backoff.
173+until it does. The logic for determining how many packets to send or re-send at what time is performed by an Ames-specific variant of TCP's "NewReno" congestion control algorithm.
175174
176−Once all packets are received, the receiving Ames decrypts them, deserializes
177−them, and puts them back together to form a message.
175+As each packet in a message is received, Ames decrypts it and stores the message fragment. Once it's received every packet for a message, Ames concatenates the fragments back into a single large atom and uses `+cue` to deserialize that back into the original message noun.
178176
179177
180178
181179### Acks and Nacks
182180
183−In this section we discuss acks and nacks. Ack is short for acknowledgement, which are small
184−packets attesting that packets were successfully received. Ames makes use of
185−acks to maintain synchrony between two communicating parties. Nacks are 'negative
181+In this section we discuss acks and nacks. In Ames, an "ack", short for "acknowledgment", is a small packet attesting that a piece of information (either a packet or a whole message) was received. Ames makes use of
182+acks to maintain synchronization between two communicating parties. Nacks are 'negative
186183acknowledgments' and are used when something goes wrong.
187184
188185#### Acks
189186
190−Every message (i.e. a `%plea`, `%boon`, or naxplanation) is split up by Ames into some number
187+Every message (i.e. a `%plea` or `%boon`) is split up by Ames into some number
191188of _fragments_ that are 1kB in size or less. The fragments are then encrypted
192189and encapsulated into
193190packets and sent along a flow. The message will be considered successfully
@@ -195,10 +192,10 @@ received once the sender has received the appropriate set of acks in response,
195192defined as follows.
196193
197194There are two types of acks: fragment acks and message acks. Acks are
198−not considered messages, and thus are not `%plea`s or `%boon`s, and so are not
199−required to appear in a particular order. Given a message split into N
195+not considered messages, and thus are not `%plea`s or `%boon`s. Given a message split into N
200196fragments, the sender of the message will expect N-1 fragment acks followed
201−by exactly one message ack. This is because the receiver
197+by exactly one message ack (ignoring any duplicate packets, which are idempotent
198+from the perspective of the application). This is because the receiver
202199will send a fragment ack for the first N-1 packets it received, and what
203200would have been the final fragment ack will instead be a message ack.
204201
@@ -206,7 +203,7 @@ Acks are considered to be part of the flow in which that `%plea` or
206203`%boon` lives, as the packets containing their fragments and packets acking the
207204receipt of those packets are considered to be what makes up a given message.
208205Thus a message-level ack must be received before the next message on the flow
209−can begin. The full story is more complicated than this, see the section on
206+can begin. The full story is more complicated than this; see the section on
210207[flows](#flows).
211208
212209
@@ -216,42 +213,46 @@ A nack indicates a negative acknowledgement to a `%plea`, meaning that the
216213requested action was not performed.
217214
218215`%boon`s and naxplanations are never nacked.
219−Individual packets are never nacked, only complete `%plea` messages. This works
220−because only complete packets ever make it to Ames, as malformed
221−packets will be discarded by the Ames I/O module in the
222−[King](#the-serf-and-the-king). Therefore there is no need for Ames to do
223−something like nack a packet whose checksum does not match the `+mug` of the
224−body.
225−
226−A nack will be accompanied by a naxplanation, which is a third type of message
227−separate from `%plea`s and `%boon`s. Ames won't give the vane that requested the
216+Individual packets are also never nacked, only complete `%plea` messages are.
217+Whether a malformed packet causes a `%plea` to be nacked depends on its content.
218+In the case of an incorrect checksum or a failure to decrypt then Ames drops the
219+packet and it is as though it never happened. However, if the packet does
220+decrypt and has invalid ciphertext (i.e. something other than a jammed
221+`$shutpacket` data structure), then Ames will nack the whole `%plea` since that
222+indicates that the peer is misbehaving. Eventually Ames should also present a
223+warning to the user that the peer is untrustworthy.
224+
225+A nack will be accompanied by a naxplanation, which is a special type of`%boon`
226+that uses its own `bone` (see [flows](#flows)). Ames won't give the vane that requested the
228227initial `%plea` a nack until it also receives the naxplanation, which it will send to
229228the vane as a `%done` gift. Naxplanations may only be acked, never nacked.
229+Furthermore, naxplanations can only ever be sent as a rejection of a `%plea` -
230+the receiver will never both perform a `%plea` and return a naxplanation.
230231
231232#### (N)ack packets
232233
233−The contents of a given (n)ack packet are deterministic. The `content` (i.e. the
234−encrypted portion of the packet) of a fragment ack is obtained by encrypting the `+jam` of the
234+A fragment ack's contents (before encryption) are a pure function of the
235235following noun:
236−
237236```hoon
238237[our-life her-life bone message-num fragment-num]
239238```
239+This means all re-sends of an ack packet will be bitwise identical to each other, unless one of the peers changes its encryption keys.
240+
240241Each datum in this noun is an atom with the aura `@ud` or an aura that nests
241242under `@ud`.
242243
243244Here, `our-life` refers to the [`life`](@/docs/glossary/breach), or revision
244245number, of the acking ship's networking keys, and `her-life` is the `life` of
245−the ack-receiving ship's networking keys. `bone` is an opaque number identifying the flow, `message-num` denotes the number of the
246−message in the flow identified by `bone`, and
247−`fragment-num` denotes the number of the fragment of the message identified by
248−`message-num` being acked.
246+the ack-receiving ship's networking keys. `bone` is an opaque number identifying
247+the flow. `message-num` denotes the number of the
248+message in the flow identified by `bone`. `fragment-num` denotes the number of
249+the fragment of the message identified by `message-num` that is being acked.
249250
250−A message (n)ack is an extended fragment ack that is obtained by encrypting the
251+A message (n)ack is a different kind of ack that is obtained by encrypting the
251252`+jam` of the following noun:
252253
253254```hoon
254−[our-life her-life bone message-num fragment-num ok=? lag=@dr]
255+[our-life her-life bone message-num ok=? lag=@dr]
255256```
256257`ok` is a flag that is set to `%.y` for a message ack and `%.n` for a message
257258nack. In the future, `lag` will be used to
@@ -263,22 +264,22 @@ describe the time it took to process a message, but for now it is always zero.
263264Flows are asymmetric communication channels along which two ships send and
264265receive packets, and all Ames packets are part of some flow.
265266
266−Flows are asymmetric in that one ship is always the sender of
267−`%plea`s and the other is always the sender of `%boon`s on a given flow. Thus ships will
268−typically have multiple flows between them.
267+To create a new flow, a ship sends a
268+`%plea` to another ship. Only the creator of the flow may send `%plea`s, and the
269+other party may only send `%boon`s. In this sense flows are asymmetric.
269270
270271The sequence of `%plea`s in a flow is totally ordered, though
271272the packets which make them up need not be. `%boon`s are totally ordered in the
272273same fashion, but there is not a coordinated ordering between `%plea`s and
273274`%boon`s in a given flow beyond the implicit one arising from the fact that a
274−`%boon` is always a response to a `%plea`.
275+`%boon` is always a response to a `%plea`. A `%plea` can give rise to zero, one,
276+or many `%boon`s.
275277
276278Inside of Ames, each flow has four sequential opaque `@ud`s
277279called bones that are unique to that flow. Thus the flow itself is often
278−referred to by its first bone. The set of types of packets is partitioned into
279−four subsets, each of which is assigned a bone. Each bone is a one-way street
280+referred to by its first bone. Each bone is a one-way street
280281for packets to travel along, so e.g. acks to packets making up a `%plea` are
281−sent along different bones.
282+sent along a different bone than the `%plea`.
282283
283284We give an example of such a partition. Let flow 12 be a flow between `~bacbel-tagfeg` and `~worwel-sipnum` with
284285`~bacbel-tagfeg` as the `%plea` sender. Then bones 12-15 are associated with the
@@ -290,7 +291,7 @@ flow, and the types of packets for each bone are:
290291 - bone 15, naxplanations to `~bacbel-tagfeg`.
291292
292293Each bone is handled separately by congestion control, and this is the reason
293−for their segregation. For example, say a two packet `%plea` is sent on bone 12,
294+for their segregation. For example, say a two-packet `%plea` is sent on bone 12,
294295with `~bacbel-tagfeg` requesting to join a group on `~worwel-sipnum`.
295296Then `~worwel-sipnum` can ack the first packet on bone 13, and then send a nack
296297on bone 13 as well. A nack by itself contains no information as to why the nack