tweak: add named states to RFCs 0036, 0037 per issue #408

0000-template-protocol.md

@@ -126,13 +126,42 @@ Sample messages that are presented in the narrative should also be checked
 in next to the markdown of the RFC, in [DIDComm Plaintext format](
 https://github.com/hyperledger/aries-rfcs/tree/master/features/0044-didcomm-file-and-mime-types#didcomm-messages-dm).
 
-#### Adoption Messages
+##### Adopted Messages
+
+Many protocols should use general-purpose messages such as [`ack`](
+https://github.com/hyperledger/indy-hipe/pull/77) and [`problem-report`](
+https://github.com/hyperledger/indy-hipe/pull/65)) at certain points in
+an interaction. This reuse is strongly encouraged because it helps us avoid
+defining redundant message types--and the code to handle them--over and
+over again (see [DRY principle](https://en.wikipedia.org/wiki/Don't_repeat_yourself)).
+
+However, using messages with generic values of `@type` (e.g., `"@type":
+"https://didcomm.org/notification/1.0/ack"`)
+introduces a challenge for agents as they route messages to their internal
+routines for handling. We expect internal handlers to be organized around
+protocols, since a protocol is a discrete unit of business value as well
+as a unit of testing in our agent test suite. Early work on agents has
+gravitated towards pluggable, routable protocols as a unit of code
+encapsulation and dependency as well. Thus the natural routing question
+inside an agent, when it sees a message, is "Which protocol handler should
+I route this message to, based on its @type?" A generic `ack` can't be
+routed this way.
+
+Therefore, we allow a protocol to __adopt__ messages into its namespace.
+This works very much like python's `from module import symbol` syntax.
+It changes the `@type` attribute of the adopted message. Suppose a `rendezvous`
+protocol is identified by the URI `https://didcomm.org/rendezvous/2.0`,
+and its definition announces that it has adopted generic 1.x `ack`
+messages. When such `ack` messages are sent, the `@type` should now use
+the alias defined inside the namespace of the `rendezvous` protocol:
+
+![diff on @type caused by adoption](concepts/0003-protocols/adoption.png)
 
 Adoption should be declared in an "Adopted" subsection of "Messages" in
 a protocol RFC. When adoption is specified, it should include a __minimum
 adopted version__ of the adopted message type: "This protocol adopts
 `ack` with version >= 1.4". All versions of the adopted message that share
-the same major number should be compatible, given the [semver rules](https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0003-protocols/semver.md)
+the same major number should be compatible, given the [semver rules](concepts/0003-protocols/semver.md)
 that apply to protocols.
 
 ### Constraints

concepts/0003-protocols/README.md

@@ -63,7 +63,7 @@ When "protocol" is used in an Aries context without any qualifying adjective, it
 The familiar world of web APIs is a world of protocols, but it comes with constraints antithetical to decentralized identity:
 
 * It assumes all interactions are between a client and a server--either two parties, or N parties mediated by a central server. Thus, the server is a natural locus for surveillance and hacking.
-* It assumes security is assymetric--not using DIDs, but driven by certs on a server and by a session for the client.
+* It assumes security is asymmetric--not using DIDs, but driven by certs on a server and by a session for the client.
 * It assumes the transport is HTTP. This is problematic for pure mobile-to-mobile, or for use cases where the transport is complex or asymmetric.
 * Because the server can never initiate an interaction, it requires at least one party to be continuously online.
 
@@ -174,13 +174,13 @@ primary message family.
 
 A protocol has the following ingredients:
 
-* [_Name_](template.md#name-and-version-under-tutorial) and [semver-compatible
+* [_Name_](../../0000-template-protocol.md#name-and-version) and [semver-compatible
   version](semver.md)
 * [_URI_ that uniquely identifies it](uris.md)
-* [_Messages (primary message family)_](template.md#messages-under-tutorial)
-* [_Adopted messages_](template.md#adopted-messages)
-* [_Roles_](template.md#roles-under-tutorial)
-* [_State_ and _sequencing rules_](template.md#states-under-tutorial)
+* [_Messages (primary message family)_](../../0000-template-protocol.md#messages)
+* [_Adopted messages_](../../0000-template-protocol.md#adopted-messages)
+* [_Roles_](../../0000-template-protocol.md#roles)
+* [_State_ and _sequencing rules_](../../0000-template-protocol.md#states)
 * _Events that can change state_ -- notably, _messages_, but also _errors_,
 _timeouts_, and other things
 * _Constraints that provide trust and incentives_
@@ -190,8 +190,8 @@ _timeouts_, and other things
 
 To define a protocol, write an RFC. Specific instructions for
 protocol RFCs, and a discussion about the theory behind detailed
-protocol concepts, are given in the [Template for Protocol RFCs](
-template.md). The [tictactoe protocol](tictactoe/README.md) is
+protocol concepts, are given in the [Instructions for Protocol RFCs](
+instructions.md) and in the [Protocol RFC Template](../../0000-template-protocol.md). The [tictactoe protocol](tictactoe/README.md) is
 also attached to this RFC as an example.
 
 [![tictactoe protocol](tictactoe/tile.png)](tictactoe/README.md)

concepts/0003-protocols/instructions.md

@@ -0,0 +1,10 @@
+# Instructions for Protocol RFCs
+
+A protocol RFC conforms to general RFC patterns, but includes some
+specific substructure.
+
+[![template sections](template-sections.png)](
+https://docs.google.com/presentation/d/15UAkh_2WfDk7wlto7pSL7YU9NJr_XVMgGAOeNIRbzK8/edit#slide=id.g5609c67f13_0_113)
+
+Please see the [special protocol RFC template](../../0000-template-protocol.md) for details.### "Name and Version" under "Tutorial"
+

concepts/0003-protocols/semver.md

@@ -11,7 +11,7 @@ An individual message type can add new optional fields, or deprecate
 existing fields, [with only a change to its protocol's minor
 version](https://semver.org/#spec-item-7).
 Similarly, a protocol can add new message types (or [adopted
-ones](template.md#adopted-messages)) with only a change
+ones](../../0000-template-protocol.md#adopted-messages)) with only a change
 to the minor version. It can announce deprecated fields. It can add additional
 semantics around optional decorators. These are all backwards-compatible
 changes, also requiring only a minor version update.