I’ve added some new plan workflow visualizations to the documentation, and revised / expanded the text with more details. On our technical calls we have walked through these drawings a few times and it seems to be at a good spot.
Here are the major changed sections:
The Plan Proposal Workflow
Often, actors starting a new relationship will not have a plan already in place, or actors with an existing relationship may want to modify it. To assist, sandpiper provides a workflow to develop these in a semi-automated fashion, through the API’s plans endpoint (see the OpenAPI schema for more details about specific payloads and parameters).
Humans may still be needed to fill in the details of their subscriptions, and to approve the new plan, but there is no need to have the full document ready to go before logging in. Instead, the initiator can log in with a blank plan; in that case they will be given access only to the plans endpoint. From there they can proceed with new plan creation or act on existing plans to which they have been party.
New Plan Creation
New plans start with a Fragment Plan — a stub plan document that contains only the primary actor’s information and a plan UUID.
The primary actor is responsible for supplying the fragment plan, because it is their information that populates it. The /plans/invoke endpoint provides (if the primary is the respondent) or accepts (if the primary is the initiator) these documents.
Once they have obtained a fragment from the primary, the secondary actor can then enter their details in the Secondary domain, add subscriptions to the Communal plan domain, and apply a new Plan UUID. They provide this to the primary as a Proposed Plan.
The primary can accept, modify, or reject this proposal (see Proposed Plan Approval).
Existing Plan Modification
For actors with an existing plan, or one that is still waiting on approval, either side may at some point want to change their agreement. In this case, there is no need to begin with a fragment plan, but they do need to provide a clear indication that this is a modification or replacement of an older plan. This can be done using the replaces_plan_uuid payload value in the API (see the YAML file for details).
In this case, rather than starting from a fragment, the modifying actor can start from the existing plan, alter the details they want to adjust in their actor domain (Primary or Secondary) and/or the Communal domain, and provide a new plan UUID. Finally, they can then propose this plan to the other party.
Proposed Plan Approval
Whether the plan is modified or completely new, once it has been proposed, the candidate plan goes through Plan Approval. The Sandpiper Framework defines the Plan Status, an attribute of plans shared between two actors, that tracks the state of the plan between the two participants. The full set of statuses and their descriptions are available in Appendix A: Plan Status.
Plan fragments do not have a status; they may be retained for an Actor’s records and processing, but because they are not complete, they are not part of the Sandpiper plan registry. Only upon proposal are they available for mutual recall and operation.
When an initiator connects to a respondent who has new plans to propose, it is the respondent’s job to notify the initiator using the login message that there are new pending plans to review. This is necessary because either side can modify the agreement, but in a REST API only one side can initiate communication.
The Sandpiper Framework 