feat(core): gateway-agnostic PaymentProvider interface (Stripe adapter + mock) - #18

Thanks for putting this together. The direction is good, and I like the intent of introducing a gateway-agnostic seam with a Stripe adapter. Kudos to the additional mock provider, registry, and separate package export.

I’m going to request changes before merging, because I don’t think the abstraction is safe enough yet to become the foundation for the follow-up checkout/webhook wiring.

Main blockers:

1. providerReference is currently ambiguous. The Stripe adapter returns a Checkout Session ID from initCheckout, but refund() later treats providerReference as a PaymentIntent ID. That will break Stripe refunds once this is wired into real flows. I think we need to split these concepts, e.g. checkoutReference / paymentReference / provider transaction reference.

2. The normalized webhook event loses the provider event ID. The current Stripe webhook route dedupes using event.id, but NormalizedPaymentEvent does not expose a providerEventId. Without that, the generic webhook route cannot preserve current retry/idempotency behaviour.

3. InitCheckoutInput is currently too narrow to replace the existing hosted checkout route. The current Stripe flow supports shipping options, billing address collection, Stripe Tax, subscription mode/trials, subscription metadata, Connect transfer data, and application fees. The adapter hard-codes mode: "payment" and only passes a minimal subset through, so wiring routes to this interface would regress existing Stripe behaviour.

4. Billing address is not mapped in the Stripe adapter. customer_details.address should become billingAddress, and we should preserve the same billing/shipping fallback behaviour the current webhook route has, especially for digital-only carts.

5. Refund idempotency is too coarse. refund:${providerReference}:${amount} means two legitimate partial refunds of the same amount against the same payment could collapse into one Stripe idempotency key. We need an explicit refund request ID or idempotency key in CreateRefundInput.

6. registerPaymentProvider() silently overwrites existing providers with the same ID. That could accidentally replace stripe or another registered provider. I’d prefer duplicate IDs to throw unless an explicit override option is passed.

There are also a few smaller issues worth cleaning up:

• supportedCurrencies() says it returns ISO currency codes, but Stripe returns ["*"]. The type should reflect that or become a supportsCurrency(currency) check.
• The mock provider appends &mock=1 even when the URL has no query string.
• mock.parseWebhookEvent() throws on invalid JSON, while the Stripe adapter returns an unhandled event.
• Some comments say checkout/webhook routes are already refactored to use PaymentProvider, but this PR explicitly defers that wiring.
• CI is green, but the test step is continue-on-error, so the check does not prove tests passed.

Overall: I’m supportive of the approach, but I’d like the seam tightened before merge so the follow-up wiring does not introduce payment, refund, or webhook regressions.