[TortoiseWolfe]

Closes #1192
Refs #1184

Hosted checkout — the path real buyers take — could not be fulfilled. handlePaymentCheckout
looked the intent up by session.metadata?.intent_id, and create-stripe-checkout never sets
session-level metadata. It sets payment_intent_data.metadata.intent_id (which lands on the
PaymentIntent, not the Session) and client_reference_id.

Measured, not inferred

A real live Checkout Session created by the deployed function on 2026-09-17:

session.metadata     = {}
client_reference_id  = "516bf680-e568-445a-98da-6a04a40d9589"   ← our intent id, correct

And the corroborating state:

payment_results	0 rows for the life of the project
every historical payment_intent.succeeded	related_payment_id: null — {handled:false} every time
verify-stripe-session	read-only; its own header says payment_results is "the source of truth"

So neither fulfilment path had ever executed successfully, and there was no third path. A
customer who paid would have got: no payment row, an order stuck at pending, and no receipt.

The fix

Correlate by client_reference_id when session metadata is absent. That also repairs sessions
created before this change, because the field was always being set. Explicit session metadata
still wins, for forward compatibility.

The companion change is not optional. With both handlers alive they both write
payment_results, and idx_payment_results_one_succeeded_per_intent permits one succeeded row
per intent — so whichever Stripe event arrives second collides. A 500 there is retried for three
days and counts toward the endpoint being disabled, which is the exact pressure that nearly cost us
the webhook last night. Both inserts now acknowledge 23505 and still call
advanceOrderAndNotify, which is a compare-and-swap on status and returns already-advanced
rather than emailing the buyer twice.

Deliberately not adding session metadata to create-stripe-checkout: client_reference_id
already carries it, works on historical sessions, and needs no redeploy of the outbound function.

Verification

• 6/6 new, 15/15 with advance-order, 985/985 test:scripts, deno check clean.
• The mutation bites: removing the client_reference_id fallback fails 3 of 6 tests, including
  the control that proves the resolver can return both a value and null.
• The regression case is pinned explicitly — {} is truthy, so a naive session.metadata ? …
  check would still resolve to undefined. That is the bug, and a test now fails on it.

This is a prerequisite for the go-live flip in #629/#1185: flipping the publishable key while this
was broken would have meant taking real money with nothing recorded.

🤖 Generated with Claude Code