docs(client): implementation plan for the client launch sequence (#409)

[halcwb]

Description

Implementation plan for the client side of the launch sequence (UC-1) from the MainEHR integration design V8, with all server-side actions stubbed behind the final API contract.

Key points:

• Launch token erased from url and history at first presentation (Rule 39); session credential as an HttpOnly, SameSite=Strict cookie, never in a url or response body (Rule 12).
• Pure client session state machine (Anonymous | Launching | Resuming | Open | Refused | Unreachable) with a stale-request guard and retries; patient changes routed through UpdatePatient.
• IdentityProvider hop modelled as a RedirectTo launch outcome; the stub never returns it.
• Server stub fails closed under GENPRES_PROD=1, so the work can ship in alphas without holding the ShipIt release PR.
• Five PRs, each under 200 lines. The plan is to be picked up in Client/Server: Initial session interactions #574 to correct that scaffold, whose redeem-token hop has no counterpart in V8.

Reviewer note: the D1 decision (url parameters versus sealed launch token) in docs/roadmap/mvpap2019-gap-overview.md is still open. The plan is D1-neutral on the client, because the launch is opaque there.

Author checklist

• The described changes have already been described in an issue: GenPRES Hospital Integration #409
• This PR documents the plan in a markdown file in docs/implementation-plans/.
• I have used the implementation plan template.
• The plan has enough detail: any suggestions that a reviewer adds to a PR that implements the plan are likely to be relatively quick to implement.

Reviewer checklist

• The chosen approach is a good choice.
• The sequence of steps is complete and sensible.
• I have documented resources that may help with implementation.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This documentation PR defines a staged implementation plan for the GenPRES client launch sequence, including URL credential hygiene, cookie-backed sessions, an explicit client state machine, IdentityProvider return handling, patient-state cleanup, and a fail-closed server stub.

The latest revision:

• Adds an explicit Retry transition that preserves the Launch and PresentationKey.
• Limits the same-Launch no-op guard to requests already in flight.
• Clarifies that refused launches are not marked spent and may be re-verified.
• Fully addresses the outstanding retry-from-Unreachable finding.

Confidence Score: 5/5

The documentation plan appears safe to merge; the latest changes fully resolve the previously blocked retry path without introducing a new actionable issue.

The explicit Retry message now transitions Unreachable and retryable Refused states back to Launching, issues a new server call, and preserves the original Launch and presentation key. Refusals do not create the spent-mark used to cache successful outcomes, so NoBrowserIdentity retries can re-verify rather than becoming permanently refused. All earlier findings are either fully fixed or resolved with explanatory replies.

Important Files Changed

Filename	Overview
docs/implementation-plans/409-client-launch-sequence.md	Defines the complete client launch implementation plan and now provides a reachable, identity-preserving retry transition for failed launch presentations.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Launch URL received] --> B[Erase token from URL and history]
    B --> C[Present Launch with PresentationKey]
    C --> D{Outcome}
    D -->|Opened| E[Open cookie-backed session]
    E --> F[Update patient context]
    D -->|RedirectTo| G[IdentityProvider round trip]
    G --> H[Server callback opens session]
    H --> I[Resume from session route]
    D -->|Retryable refusal| J[Refused with Launch and key]
    C -->|Transport failures exhausted| K[Unreachable with Launch and key]
    J -->|Retry| C
    K -->|Retry| C
    D -->|NoRole| L[Offer anonymous open]
    L --> M[Clear patient and derived context]
    E -->|Close| M

Loading

_{Reviews (5): Last reviewed commit: "docs(client): add an explicit retry tran..." | Re-trigger Greptile}