Rework orphan mitigation section

Author: Matt McNeeney

spec.md

@@ -29,7 +29,7 @@
   - [Fetching a Service Binding](#fetching-a-service-binding)
   - [Unbinding](#unbinding)
   - [Deprovisioning](#deprovisioning)
-  - [Orphans](#orphans)
+  - [Orphan Mitigation](#orphan-mitigation)
 
 ## API Overview
 
@@ -250,10 +250,11 @@ Where the `value`, when decoded, is:
 ```
 
 Note that not all messages sent to a Service Broker are initiated by an
-end-user of the Platform. For example, during orphan mitigation or during the
-querying of the Service Broker's catalog, the Platform might not have an
-end-user with which to associate the request, therefore in those cases the
-originating identity header would not be included in those messages.
+end-user of the Platform. For example, during
+[Orphan Mitigation](#orphan-mitigation) or during the querying of the Service
+Broker's catalog, the Platform might not have an end-user with which to
+associate the request, therefore in those cases the originating identity header
+would not be included in those messages.
 
 ## Vendor Extension Fields
 
@@ -703,9 +704,9 @@ containing error code `"ConcurrencyError"` (see
 a helpful error message in the `description` field such as `"Another operation
 for this Service Instance is in progress."`.
 
-Note that per the [Orphans](#orphans) section, this error response does not
-cause orphan mitigation to be initiated. Therefore, Platforms receiving this
-error response SHOULD resend the request at a later time.
+This error response MUST not cause orphan mitigation to be initiated (see the
+[Orphan Mitigation](#orphan-mitigation) section). Therefore, Platforms receiving
+this error response SHOULD resend the request at a later time.
 
 Brokers MAY choose to treat the creation of a Service Binding as a mutation of
 the corresponding Service Instance - it is an implementation choice. Doing so
@@ -779,11 +780,10 @@ For success responses, the following fields are defined:
 }
 ```
 
-If the response contains `"state": "failed"` then the Platform MUST send a
-deprovision request to the Service Broker to prevent an orphan being created on
-the Service Broker. However, while the Platform will attempt
-to send a deprovision request, Service Brokers MAY automatically delete
-any resources associated with the failed provisioning request on their own.
+For asynchronous provision operations, if the response contains
+`"state": "failed"`, then the Platform MAY need to send a deprovision request to
+the Service Broker to prevent an orphan being created (see the
+[Orphan Mitigation](#orphan-mitigation) section).
 
 ## Polling Last Operation for Service Bindings
 
@@ -857,9 +857,9 @@ For success responses, the following fields are defined:
 }
 ```
 
-If the response contains `"state": "failed"` then the Platform MUST send an
-unbind request to the Service Broker to prevent an orphan being created on
-the Service Broker.
+If the response contains `"state": "failed"`, then the Platform MAY need to send
+an unbind request to the Service Broker to prevent an orphan being created (see
+the [Orphan Mitigation](#orphan-mitigation) section).
 
 ## Polling Interval and Duration
 
@@ -949,11 +949,10 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc
 | 409 Conflict | MUST be returned if a Service Instance with the same id already exists but with different attributes. |
 | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous provisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. |
 
-Responses with any other status code MUST be interpreted as a failure. See
-the [Orphans](#orphans) section for more information related to whether
-orphan mitigation needs to be applied. While a Platform might attempt
-to send a deprovision request, Service Brokers MAY automatically delete
-any resources associated with the failed provisioning request on their own.
+Responses with any other status code MUST be interpreted as a failure. If a
+failure occurs, then the Platform MAY need to send a deprovision request to the
+Service Broker to prevent an orphan being created (see the
+[Orphan Mitigation](#orphan-mitigation) section).
 
 #### Body
 
@@ -1341,11 +1340,10 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc
 | 409 Conflict | MUST be returned if a Service Binding with the same id, for the same Service Instance, already exists but with different parameters. |
 | 422 Unprocessable Entity | MUST be returned if the Service Broker requires that `app_guid` be included in the request body. The response body MUST contain error code `"RequiresApp"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service supports generation of credentials through binding an application only."`. Additionally, if the Service Broker rejects the request due to a concurrent request to create a Service Binding for the same Service Instance, then this error MUST be returned (see [Blocking Operations](#blocking-operations)). This MUST also be returned if the Service Broker only supports asynchronous bindings for the Service Instance and the request did not include `?accepts_incomplete=true`. In this case, the response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Instance requires client support for asynchronous binding operations."`. |
 
-Responses with any other status code MUST be interpreted as a failure and an
-unbind request MUST be sent to the Service Broker to prevent an orphan being
-created on the Service Broker. However, while the platform will attempt
-to send an unbind request, Service Brokers MAY automatically delete
-any resources associated with the failed bind request on their own.
+Responses with any other status code MUST be interpreted as a failure. If a
+failure occurs, then the Platform MAY need to send an unbind request to the
+Service Broker to prevent an orphan being created (see the
+[Orphan Mitigation](#orphan-mitigation) section).
 
 #### Body
 
@@ -1616,40 +1614,49 @@ For success responses, the following fields are defined:
 }
 ```
 
-## Orphans
+## Orphan Mitigation
 
 The Platform is the source of truth for Service Instances and Service Bindings.
 Service Brokers are expected to have successfully provisioned all of the Service
 Instances and Service Bindings that the Platform knows about, and none that it
 doesn't.
 
-Orphans can result if the Service Broker does not return a response before a
-request from the Platform times out (typically 60 seconds). For example, if a
-Service Broker does not return a response to a provision request before the
-request times out, the Service Broker might eventually succeed in provisioning
-a Service Instance after the Platform considers the request a failure. This
-results in an orphan Service Instance on the Service Broker's side.
+Orphaned Service Instances and Service Bindings  MAY be created by in any of the
+following scenarios:
+* The Service Broker does not return a response before a request from the
+Platform times out (typically 60 seconds). The Service Broker might eventually
+succeed in creating a resource, however the Platform MAY have already considered
+the request a failure.
+* A synchronous [Provisioning](#provisioning) request fails.
+* A call to the
+[Polling Last Operation for Service Instances](#polling-last-operation-for-service-instances)
+endpoint returns `"state": "failed"` for an asynchronous provisioning request
+* A synchronous [Binding](#binding]) request fails
+* A call to the
+[Polling Last Operation for Service Bindings](#polling-last-operation-for-service-bindings)
+endpoint returns `"state": "failed"` for an asynchronous binding request
+* The Platform encounters an internal error creating a Service Instance or
+Service Binding (for example, saving to the database fails).
 
-To mitigate orphan Service Instances and Service Bindings, the Platform SHOULD
+To mitigate orphaned Service Instances and Service Bindings, the Platform SHOULD
 attempt to delete resources it cannot be sure were successfully created, and
 SHOULD keep trying to delete them until the Service Broker responds with a
-success.
+success. Service Brokers MAY automatically delete any resources they believe to
+be orphaned on their own. Note that the Platform MAY allow end users to
+determine when orphan mitigation occurs, in order to allow end users to
+investigate any failures.
 
 Platforms SHOULD initiate orphan mitigation in the following scenarios:
 
 | Status Code Of Service Broker Response | Platform Interpretation Of Response | Platform Initiates Orphan Mitigation? |
 | --- | --- | --- |
 | 200 | Success | No |
 | 200 with malformed response | Failure | No |
+| 200 with `"state": "failed"` (applicable to [Polling Last Operation for Service Instances](#polling-last-operation-for-service-instances) and [Polling Last Operation for Service Bindings](#polling-last-operation-for-service-bindings) endpoints) | Failure | Yes |
 | 201 | Success | No |
 | 201 with malformed response | Failure | Yes |
 | All other 2xx | Failure | Yes |
 | 408 | Client timeout failure (request not received at the server) | No |
 | All other 4xx | Request rejected | No |
 | 5xx | Service Broker error | Yes |
 | Timeout | Failure | Yes |
-
-If the Platform encounters an internal error provisioning a Service Instance or
-Service Binding (for example, saving to the database fails), then it MUST at
-least send a single delete or unbind request to the Service Broker to prevent
-the creation of an orphan.