feat(ucp): negotiate payment method on checkout completion, escalate to browser handoff when none is supported

[Lukas Rump (lukasrump)]

What & why

Today the checkout completer places an order regardless of whether the client can
actually pay through any handler the shop advertises. For x402 (order-first,
settle-after) that's by design, but it means a client that supports none of the
advertised payment_handlers either ends up with a placed, never-payable order or
no path forward.

This adds a deterministic, opt-in payment-method negotiation:

• The client commits a handler via CheckoutUpdateRequest.payment (PaymentInstrument).
• On completion, if the committed handler is registered in the SDK
  PaymentHandlerRegistry, the order is placed as today.
• Otherwise (no commitment, or an unsupported/declined handler) the checkout is
  returned as requires_escalation with a continue_url and no order is placed —
  the UCP-standard fallback that lets a human finish in a browser.

It's driven by what the client agrees to pay with, not by what the shop offers, so
the shop never silently places an order (e.g. an unpaid invoice order) against a method
the agent didn't choose.

Opt-in / non-breaking

Gated behind a per-channel policy requireCommittedPaymentMethod (default off):

• off (default): unchanged behaviour — completion proceeds without a committed
  payment method (spec-conformant: the UCP payment object is optional).
• on: completion requires a committed, settle-able handler; otherwise it escalates.

So this changes nothing unless a merchant opts in — suitable for agent-only channels
that must not accumulate phantom unpaid orders. The flag is read via SystemConfigService
(SwagAgenticCommerce.config.requireCommittedPaymentMethod); an admin toggle (config.xml)
is an easy follow-up.

Spec alignment

• PaymentInstrument on update and payment_handlers advertisement are standard UCP.
• requires_escalation + continue_url is the spec's prescribed fallback for a
  capability/negotiation failure.
• Payment remains optional per the spec; the strict behaviour is opt-in only.

Scope

• Ucp/Checkout/CheckoutSessionStore.php, CheckoutSessionManager.php — persist/read the committed handler id.
• Ucp/Adapter/ShopwareCheckoutAdapter.php — capture the commitment on update; policy-gated escalation on complete.
• Tests + docs/payment-method-negotiation.md.
• continue_url can point at any merchant checkout; a signed cart-adopting handoff route is deployment-specific and intentionally not included here.

Coordination note

feat/ucp-ap2-mandates reworks completion to a CheckoutCompleteRequest /
verifiedCheckout API. This targets main; once that branch lands, the escalation
gate should move into the request-based flow. Happy to rebase/adapt.

Testing

Unit test added for the escalation path (policy on + no supported handler committed ⇒
requires_escalation, completer never invoked → no order). Please run PHPStan/PHPUnit in
CI — the branch was authored without a local PHP toolchain.