# ADR 0025. Provider Launch Sessions and PlayerPal Widget Distribution

## Status
Accepted.

## Context
ADR 0015 keeps PlayerPal out of game launch and settlement, while ADR 0017
defines operator-led linking. A realistic provider integration still needs to
bootstrap a cross-origin game, optionally present PlayerPal inside the
provider-owned experience, and support both operator-led and provider-led
adoption without making browser payloads authoritative.

Copying the widget into a provider build makes its provenance and upgrade path
provider-controlled. Passing launch credentials in an iframe URL leaks them
through browser history, logs and referrers. Letting a provider call an
operator to perform linking also reverses the intended ownership boundary.

## Decision
1. The operator creates a short-lived **Provider launch session** through the
   provider's authenticated backend API. PlayerPal is not called in this path.
2. Browser bootstrap uses a single-use, expiring POST body. Access tokens,
   signed assertions and player aliases never appear in the iframe URL. The
   provider backend consumes the bootstrap and supplies immutable, sanitized
   session context to its own game client. When the game client is on a
   different origin from the consume endpoint, the handoff uses same-tab
   `window.name` (never query/fragment secrets); the provider page then
   publishes verified context to the PlayerPal widget via a same-document
   event. Parent `postMessage` is not used for launch context.
3. The operator remains authoritative for the seamless wallet. The provider
   owns game mathematics and Provider rounds; PlayerPal receives only
   asynchronous, post-settlement Activity batches from the provider backend.
4. Providers load an exact immutable PlayerPal widget build from a
   PlayerPal-controlled asset origin with Subresource Integrity. They do not
   rebuild or redistribute the widget. Widget failure never blocks play.
5. Integrations may use three **Linking modes**:
   - **pre-linked** — an existing provider alias is present at launch;
   - **operator-led** — the operator completes linking before launch and places
     only the provider alias in launch metadata;
   - **provider-led** — the provider's Link broker creates and exchanges a
     provider-scoped Link intent under authenticated integration scope.
6. A provider never calls an operator to perform linking. If an operator-led
   launch has no alias, the provider continues without PlayerPal.
7. The provider surface receives only its integration-scoped
   `pp_plr_prv_…` alias and coarse connection/outbox status. Global Points,
   ledger details, operator aliases and the private PlayerPal ID stay on
   PlayerPal-controlled surfaces.

## Consequences
- Extends ADRs 0015 and 0017; it does not replace their asynchronous sidecar or
  PlayerPal-hosted consent requirements.
- The local demonstration needs distinct operator, provider and PlayerPal
  backend boundaries and separately owned persistence, even when infrastructure
  is shared on one development machine.
- A refreshed or replayed consumed bootstrap cannot resume a game. The operator
  requests a new Provider launch session; persisted wallet and round state make
  recovery idempotent.
- The original PixiJS game remains play-money demonstration software and is not
  certified real-money gambling mathematics.