clarify ACKs

Signed-off-by: dhh1128 <daniel.hardman@sicpa.com>

.gitignore

@@ -1,3 +1,4 @@
 .idea/
 .vscode/
+.DS_Store
 node_modules

docs/spec-files/out_of_band.md

@@ -194,7 +194,7 @@ These redirects may not be required in many cases, for example,
 
 
 ##### Reference
-During the protocol execution sender can securely send [`web-redirect`](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0700-oob-through-redirect#web-redirect-decorator) info as part of messages concluding protocol executions like [acknowledgement and problem report](problems.md).
+During the protocol execution sender can securely send [`web-redirect`](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0700-oob-through-redirect#web-redirect-decorator) info as part of messages concluding protocol executions, like [a formal acknowledgement message](#acks) or a [problem report](#problem-reports).
 Once protocol is ended then receiver can optionally choose to redirect by extracting the redirect information from the message.
 
 Example acknowledgement message from verifier to prover containing web redirect information.

docs/spec-files/problems.md

@@ -14,7 +14,23 @@ In many cases, a DIDComm message SHOULD use the `expires_time` header to announc
 
 #### ACKs
 
-Any DIDComm message MAY use the `please_ack` header to request a read receipt from a recipient. Cooperative parties who wish to honor this request MUST include an `ack` header on a subsequent message, where the value of the header is an array that contains the `id` of one or more messages being acknowledged.
+DIDComm provides several tools that let one party acknowledge messages sent by another.
+
+[Threading](#threading) has some implicit built-in ACK semantics. In a two-party protocol that consists of message types mapping unambiguously to progressive steps, each message that moves forward is an implicit ACK of the message that preceded it. 
+
+When [DIDComm `problem-report`s](#problem-reports) constitute reactions to a preceding message (as opposed to when they signal problems in external circumstances), they also function as an ACK.
+
+However, more explicit and more powerful ACKs are sometimes needed. They can prove that parties have a shared view of state at a particular time, test the functioning of a transport, help debug surprising silence, fine-tune timeouts, and speed up remedial action.
+
+To facilitate this, any innermost DIDComm plaintext message MAY use the `please_ack` header to politely request a read receipt from a recipient. The header's value is an array of strings that clarify when the ACK is requested. The following values are defined: "receipt", "outcome". If "receipt" is present, then the request is to ACK as soon as the message is received. If "outcome" is present, then the request is to ACK as soon as the message is fully processed. This distinction is more likely to be meaningful if the message time-consuming processes (e.g., triggers a request for human input). A future extension of DIDComm messaging may define time-oriented tokens as values in this array (e.g., to request an ACK if no other response is forthcoming after N minutes).
+
+The presence of the `please_ack` header does not create an obligation on the part of the recipient. However, cooperative parties who wish to honor such a request MUST include an `ack` header on a subsequent message, where the value of the header is an array that contains the `id` of one or more messages being acknowledged. Values in this array MUST appear in the order received, from oldest to most recent.
+
+>Note: The `please_ack` header SHOULD NOT be included on [`forward` messages](#routing), and MUST NOT be honored by mediators. It is only for use between ultimate senders and receivers; otherwise, it would add a burden of sourceward communication to mediators, and undermine the privacy of recipients.
+
+A plaintext message that contains the `ack` header is said to be an explicit ACK, no matter what its internal structure or message type is.
+
+Particular protocols may wish to design their own message types that convey additional information in an ACK. Custom ACK messages SHOULD include the `ack` header if they can appear at more than one step in a protocol, so it's clear what they are acknowledging. When the message type's primary purpose is to acknowledge, the type name `ack` SHOULD be used, for the sake of consistency.
 
 #### Threads
 
@@ -33,6 +49,7 @@ Other entities are notified of problems by sending a simple message called a **p
   "type": "https://didcomm.org/report-problem/2.0/problem-report",
   "id": "7c9de639-c51c-4d60-ab95-103fa613c805",
   "pthid": "1e513ad4-48c9-444e-9e7e-5b8b45c5e325",
+  "ack": ["1e513ad4-48c9-444e-9e7e-5b8b45c5e325"],
   "body": {
     "code": "e.p.xfer.cant-use-endpoint",
     "comment": "Unable to use the {1} endpoint for {2}.",
@@ -47,6 +64,8 @@ Other entities are notified of problems by sending a simple message called a **p
 
 The `pthid` header MUST be included with problem reports. Its value is the `thid` of the thread in which the problem occurred. (Thus, the problem report begins a new child thread, of which the triggering context is the parent. The parent context can react immediately to the problem, or can suspend progress while troubleshooting occurs.)
 
+The `ack` header SHOULD be included if the problem in question was triggered directly by a preceding message. (Contrast problems arising from a timeout or a user deciding to cancel a transaction, which can arise independent of a preceding message. In such cases, `ack` MAY still be used, but there is no strong recommendation.) 
+
 The `code` field is worthy of its own section; [see below](#problem-codes).
 
 The optional `comment` field contains human-friendly text describing the problem. The text MUST be statically associated with `code`, meaning that each time circumstances trigger a problem with the same `code`, the value of `comment` will be the same. This enables [localization](#i18n) and cached lookups, and it has some [cybersecurity benefits](#cybersecurity-implications). The value of `comment` supports simple interpolation with `args` (see next), where args are referenced as `{1}`, `{2}`, and so forth. 

docs/spec-files/routing.md

@@ -22,7 +22,7 @@ In this protocol, the sender and the receiver never interact directly; they only
 
 The sender can decorate the `forward` message in standard DIDComm ways: using [`~timing.expires_time`, `~timing.delay_milli` and `~timing.wait_until_time`](https://github.com/hyperledger/aries-rfcs/blob/master/features/0032-message-timing/README.md#tutorial) to introduce timeouts and delays, and so forth. However, the mediator is NOT required to support or implement any of these mixin semantics; only the core forwarding behavior is indispensable. If a mediator sees a decorator that requests behavior it doesn't support, it MAY return a [`problem-report`](https://github.com/hyperledger/aries-rfcs/blob/master/features/0035-report-problem/README.md) to the sender identifying the unsupported feature, but it is not required to do so, any more than other recipients of DIDComm messages would be required to complain about unsupported decorators in messages they receive.
 
->[[TODO: needs revision when we decide how ACKs will work and whether explicit requests for an ACK will be conveyed via headers.]] One particular decorator is worth special mention here: [`~please_ack`](https://github.com/hyperledger/aries-rfcs/blob/master/features/0015-acks/README.md#requesting-an-ack-please_ack). This decorator is intended to be processed by ultimate recipients, not mediators. If it were used with `forward` messages, it would impose a burden of backward-facing communication that mediators should not have. Furthermore, it could probe a delivery chain in a way that risks privacy for the receiver. Therefore, senders SHOULD NOT use this on `forward` messages, and mediators SHOULD NOT honor it if present. If a sender wishes to troubleshoot, the [message tracing](https://github.com/hyperledger/aries-rfcs/blob/master/features/0034-message-tracing/README.md) mechanism is recommended.
+>Note: The [`please_ack` header](#acks) SHOULD NOT be included on [`forward` messages](#routing), and MUST NOT be honored by mediators. It is only for use between ultimate senders and receivers; otherwise, it would add a burden of sourceward communication to mediators, and undermine the privacy of recipients.
 
 #### States
 

docs/spec-files/threading.md

@@ -6,7 +6,7 @@ DIDComm provides threading as foundation for extremely powerful protocol feature
 
 All plaintext DIDComm messages MUST have an `id` property, declared in the JWM header. A message without an `id` property SHOULD be considered invalid and SHOULD be rejected; it MUST NOT be interpreted as part of a multi-message interaction.
 
-The value of `id` is a short (<=32 bytes) string consisting entirely of [unreserved URI characters](https://datatracker.ietf.org/doc/html/rfc3986/#section-2.3) -- meaning that it is not necessary to [percent encode](https://en.wikipedia.org/wiki/Percent-encoding) the value to incorporate it in a URI. Beyond this requirement, its format is not strongly constrained, but use of [UUIDs (RFC 4122)](https://datatracker.ietf.org/doc/html/rfc4122) is recommended. Because of the affinity for UUIDs, this field inherits UUID case-sensitivity semantics: it SHOULD be written in lower case but MUST be compared case-insensitively.
+The value of `id` is a short (&lt;=32 bytes) string consisting entirely of [unreserved URI characters](https://datatracker.ietf.org/doc/html/rfc3986/#section-2.3) -- meaning that it is not necessary to [percent encode](https://en.wikipedia.org/wiki/Percent-encoding) the value to incorporate it in a URI. Beyond this requirement, its format is not strongly constrained, but use of [UUIDs (RFC 4122)](https://datatracker.ietf.org/doc/html/rfc4122) is recommended. Because of the affinity for UUIDs, this field inherits UUID case-sensitivity semantics: it SHOULD be written in lower case but MUST be compared case-insensitively.
 
 The value of an `id` property SHOULD be globally, universally unique; at the very least, it MUST be unique across all interactions visible to the set of parties that see a given set of interactions.