@curless/hotel-storefront 0.39.0 → 0.39.1

package/dist/huazhu/backend.js

@@ -513,6 +513,16 @@ export const createHuazhuHotels = (opts) => {
     const requestsByEmail = new WindowCounter(DAY_MS, now);
     const requestsByIp = new WindowCounter(HOUR_MS, now);
     const requestsByConversation = new WindowCounter(HOUR_MS, now);
+    /**
+     * Paying with UnionPay, asked - each ask reaches the gateway and UnionPay's
+     * test system, so each is counted, whatever it came to: by booking, by
+     * conversation and by address (2026-10-16 audit, P0-E: one booking asked
+     * 50 times bound 50 cards' worth of pages, and used up the gateway's rate).
+     */
+    const unionPayAsks = new WindowCounter(HOUR_MS, now);
+    const UNIONPAY_ASKS = { booking: 6, conversation: 12, ip: 120 };
+    /** UnionPay's page for binding a card is handed out again this long, not asked for again. */
+    const ENROLL_REUSE_MS = 30 * 60_000;
     /**
      * Bookings a request has passed the limits for and not yet written down.
      *
@@ -1266,13 +1276,15 @@ export const createHuazhuHotels = (opts) => {
             // here is taken or refunded.
             const status = b.status === 'cancelled' && p.issuedAt
                 ? 'hotel-refunds'
-                : p.lapsedAt || p.declined
-                    ? 'lapsed'
-                    : b.status === 'confirmed'
-                        ? 'paid'
-                        : p.issuedAt
-                            ? 'issued'
-                            : 'awaiting';
+                : // Not booked - turned down, written off by the follow-up queries,
+                    // lapsed: the hotel never booked it, so never charged the card.
+                    p.lapsedAt || p.declined || b.status === 'failed' || b.status === 'expired'
+                        ? 'lapsed'
+                        : b.status === 'confirmed'
+                            ? 'paid'
+                            : p.issuedAt
+                                ? 'issued'
+                                : 'awaiting';
             return {
                 method: 'unionpay',
                 amount: b.quote.total,
@@ -1368,16 +1380,16 @@ export const createHuazhuHotels = (opts) => {
         }
         return there;
     };
-    /** Huazhu's own word on a booking, at most once a minute each. */
+    /**
+     * Huazhu's own word on a booking, at most once a minute each.
+     *
+     * ⚠️ IT ONLY READS (2026-10-16 audit, P0-A). It used to move a payment on
+     * as it was asked about - outside the booking's lock, from every lookup and
+     * every few seconds from a card waiting on a payment. Payments move on in
+     * the pass, the landing page and the steps a guest takes, one at a time.
+     */
     const refresh = async (found) => {
-        // A page open for payment, or money going back, is looked at as it is
-        // asked about - the guest who just paid sees it booked without waiting
-        // for the next pass.
-        let b = found;
-        if (b.prepaid && moneyPending(b)) {
-            await settlePrepaid(b);
-            b = store.get(b.id) ?? b;
-        }
+        const b = store.get(found.id) ?? found;
         if (!b.resId || b.pendingSince !== undefined)
             return b;
         if (b.refreshedAt && now() - b.refreshedAt < 60_000)
@@ -1405,7 +1417,7 @@ export const createHuazhuHotels = (opts) => {
     const waitingWords = (b) => b.status === 'unconfirmed'
         ? `${opts.sandbox ? 'The simulated Huazhu' : 'Huazhu'} has not said whether this booking was made, and a person here is confirming it. It cannot be cancelled here until then - ask again later.`
         : `${opts.sandbox ? 'The simulated Huazhu' : 'Huazhu'} has not confirmed this booking yet - that takes up to eight minutes. It can be cancelled once it is confirmed.`;
-    const feeNow = (b) => {
+    const feeNow = (b, at = now()) => {
         const policy = policyOf(b.cancelCode);
         const amounts = {
             currency: b.quote.total.currency,
@@ -1425,7 +1437,7 @@ export const createHuazhuHotels = (opts) => {
         }
         // A room by the hour that has begun is a no-show, whatever the code says
         // about the rest of the day - see `beforeStart`.
-        if (b.hourly && now() >= arrivalInstant(b.stay.checkIn, b.hourly.start, b.tz)) {
+        if (b.hourly && at >= arrivalInstant(b.stay.checkIn, b.hourly.start, b.tz)) {
             return {
                 fee: total,
                 forbidden: false,
@@ -1433,11 +1445,11 @@ export const createHuazhuHotels = (opts) => {
                 freeUntil: undefined,
             };
         }
-        const penalty = penaltyAt(policy, b.stay.checkIn, b.tz, now());
+        const penalty = penaltyAt(policy, b.stay.checkIn, b.tz, at);
         const fee = feeFor(penalty, amounts);
         const freeUntil = b.hourly
-            ? beforeStart(freeUntilOf(policy, b.stay.checkIn, b.tz, now()), b.stay.checkIn, b.hourly.start)
-            : freeUntilOf(policy, b.stay.checkIn, b.tz, now());
+            ? beforeStart(freeUntilOf(policy, b.stay.checkIn, b.tz, at), b.stay.checkIn, b.hourly.start)
+            : freeUntilOf(policy, b.stay.checkIn, b.tz, at);
         return {
             fee: fee ?? total,
             forbidden: fee === null,
@@ -1593,7 +1605,7 @@ export const createHuazhuHotels = (opts) => {
         const contact = contactOf(row.guest);
         if (typeof contact === 'string') {
             const why = "the guest's name could not be sent to Huazhu as written";
-            store.update(id, { status: 'failed', ...(card ? { prepaid: { ...p, declined: why } } : {}) });
+            patch(id, { status: 'failed' }, card ? { declined: why } : {});
             await refundOf(id, why);
             return;
         }
@@ -1671,13 +1683,8 @@ export const createHuazhuHotels = (opts) => {
         if (refusal && card) {
             // Paid with UnionPay: the hotel charges the card, and a booking it did
             // not make it never charged - there is nothing here to give back.
-            store.update(id, {
-                status: 'failed',
-                pendingSince: undefined,
-                prepaid: {
-                    ...p,
-                    declined: `Huazhu did not take the booking: ${refusal.huazhuMessage} (${refusal.code})`.replace(/\d{12,19}/g, '****'),
-                },
+            patch(id, { status: 'failed', pendingSince: undefined }, {
+                declined: `Huazhu did not take the booking: ${refusal.huazhuMessage} (${refusal.code})`.replace(/\d{12,19}/g, '****'),
             });
             return;
         }
@@ -1704,13 +1711,11 @@ export const createHuazhuHotels = (opts) => {
         try {
             // Named by when it was decided: the same refund retried is the same refund.
             const r = await checkout.refund(p.sessionId, reason, `${row.distributorResId}-${at}`);
-            store.update(id, {
-                prepaid: { ...p, refund: { reason, at, requestId: r.requestId, status: r.status, tries } },
-            });
+            patch(id, {}, { refund: { reason, at, requestId: r.requestId, status: r.status, tries } });
             console.error(`[huazhu prepaid ${id}] refund ${r.requestId} (${r.status}) of session ${p.sessionId}: ${reason}`);
         }
         catch (err) {
-            store.update(id, { prepaid: { ...p, refund: { reason, at, tries } } });
+            patch(id, {}, { refund: { reason, at, tries } });
             if (tries >= 8 && !row.attention) {
                 const why = `the guest paid (gateway session ${p.sessionId}) and the refund could not be opened: ${err.message}`;
                 store.update(id, { attention: why, attentionAt: new Date(now()).toISOString() });
@@ -1718,6 +1723,44 @@ export const createHuazhuHotels = (opts) => {
             }
         }
     };
+    /**
+     * What a cancelled booking paid here in advance owes the guest - written in
+     * the SAME write as the cancellation (2026-10-16 audit, P0-B: written after
+     * it, a process stopped in between, Huazhu's 5402 and a cancellation made at
+     * Huazhu's end all left the money with us for good).
+     *
+     * - Free: all of it back - a refund to open.
+     * - Cancelled by the guest here, the fee the whole stay (the only kind of
+     *   rate sold paid in advance): kept as that fee.
+     * - Anything else - a part fee, or cancelled at Huazhu's end after the free
+     *   period, by the hotel or by the guest some other way: a person's to judge.
+     */
+    const owedOnCancel = (b, feeMinor, byGuest) => {
+        const p = b.prepaid;
+        if (!p?.paidAt || p.method === 'unionpay' || p.refund || p.kept)
+            return { row: {}, fields: {} };
+        if (feeMinor <= 0)
+            return {
+                row: {},
+                fields: {
+                    refund: {
+                        reason: byGuest
+                            ? 'cancelled within the free cancellation period'
+                            : 'cancelled at Huazhu within the free cancellation period',
+                        at: now(),
+                        tries: 0,
+                    },
+                },
+            };
+        if (byGuest && feeMinor >= b.quote.total.minor)
+            return { row: {}, fields: { kept: { feeMinor, at: now() } } };
+        const fee = formatMoney(money(feeMinor, b.quote.total.currency));
+        const why = byGuest
+            ? `cancelled with a fee of ${fee} of the ${formatMoney(b.quote.total)} paid (gateway session ${p.sessionId}): the difference is owed back, and a part refund is not made here`
+            : `Huazhu shows ${b.distributorResId} cancelled - not by the guest here - after its free period (a fee of ${fee} by its terms) with ${formatMoney(b.quote.total)} paid (gateway session ${p.sessionId}): whether the guest is owed it back is to be judged with Huazhu`;
+        console.error(`[huazhu prepaid ${b.id}] ⚠️ NEEDS A PERSON: ${why}`);
+        return { row: { attention: why, attentionAt: new Date(now()).toISOString() }, fields: {} };
+    };
     /**
      * A confirmation that lands a little after `payBy` was made in time - the
      * callback is seconds behind the guest. Later than this, it is never used.
@@ -1733,10 +1776,7 @@ export const createHuazhuHotels = (opts) => {
         const p = row.prepaid;
         if (row.status !== 'awaiting-payment' || !unionpay)
             return;
-        const lapse = () => store.update(row.id, {
-            status: 'expired',
-            prepaid: { ...p, lapsedAt: now(), url: undefined },
-        });
+        const lapse = () => patch(row.id, { status: 'expired' }, { lapsedAt: now(), url: undefined });
         if (!p.sessionId) {
             if (now() >= p.payBy)
                 lapse();
@@ -1763,20 +1803,21 @@ export const createHuazhuHotels = (opts) => {
                 return;
             }
             if (!card) {
-                // Handed over by the gateway and lost on the way, or never readable: the
-                // gateway gives it once, so this stay cannot be booked with it (总线程,
-                // 2026-10-15) - the guest books again and confirms on UnionPay again.
-                const why = 'UnionPay confirmed the payment, but its one-time card did not reach this connector, so the stay was not booked and nothing was charged. Ask for the booking again and confirm on UnionPay once more.';
-                store.update(row.id, {
-                    status: 'failed',
-                    prepaid: { ...p, url: undefined, declined: why },
-                });
-                console.error(`[huazhu prepaid ${row.id}] ${why}`);
+                // ⚠️ GONE FROM THE GATEWAY (410), OR NOT THIS MERCHANT'S (404) - NEVER
+                // "NOT BOOKED" BY GUESS (2026-10-16 audit, P0-A). Handed over once, to
+                // a step that may have booked it with Huazhu and then died: what
+                // Huazhu has decides. The stay waits on the follow-up queries
+                // (`Reconciler`) as any booking whose answer was lost does - booked
+                // if Huazhu has it, failed (nothing charged) if Huazhu says late in
+                // the eight minutes that it does not.
+                const cur = store.get(row.id);
+                if (!cur || cur.status !== 'awaiting-payment')
+                    return;
+                patch(row.id, { status: 'requested', pendingSince: now() }, { issuedAt: cur.prepaid?.issuedAt ?? now(), url: undefined });
+                console.error(`[huazhu prepaid ${row.id}] UnionPay's one-time card was not there to take (handed over already, or not this merchant's): asking Huazhu whether ${row.distributorResId} was booked`);
                 return;
             }
-            store.update(row.id, {
-                prepaid: { ...p, issuedAt: now(), cardLastFour: lastFour(card), url: undefined },
-            });
+            patch(row.id, {}, { issuedAt: now(), cardLastFour: lastFour(card), url: undefined });
             console.log(`[huazhu prepaid ${row.id}] UnionPay issued a one-time card ···· ${lastFour(card)}: booking it with Huazhu as CCPN`);
             await bookPaid(row.id, card);
             return;
@@ -1786,8 +1827,59 @@ export const createHuazhuHotels = (opts) => {
         if (state === 'closed' || now() >= p.payBy)
             lapse();
     };
+    /**
+     * ⚠️ ONE STEP AT A TIME ON A BOOKING - every step that moves a payment on:
+     * the pass, the landing page, paying with UnionPay instead, a cancellation
+     * (2026-10-16 audit, P0-A). A single flag for the pass alone was walked
+     * round by every lookup, which moved payments on unlocked: the one-time card
+     * taken twice, a stay Huazhu had booked written off as "not booked", a
+     * refund's record wiped and then reported as never opened.
+     */
+    const busy = new Set();
+    /** Every step under way - what a deploy's SIGTERM waits for (audit P1-3). */
+    const steps = new Set();
+    /** A step on this booking if nobody is taking one - undefined if somebody is, or the process is stopping. */
+    const ifFree = (id, fn) => {
+        if (busy.has(id) || closing)
+            return Promise.resolve(undefined);
+        busy.add(id);
+        const step = (async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                busy.delete(id);
+            }
+        })();
+        steps.add(step);
+        void step.finally(() => steps.delete(step)).catch(() => { });
+        return step;
+    };
+    /** A step on this booking once it is its turn - one under way is waited for, a few seconds at most. */
+    const inTurnFor = async (id, fn) => {
+        for (let i = 0; busy.has(id) && i < 400; i += 1)
+            await new Promise((r) => setTimeout(r, 25));
+        if (closing)
+            throw new Error('This connector is restarting. Nothing changed - ask again in a moment.');
+        if (busy.has(id))
+            throw new Error('A payment on this booking is being settled right now. Ask again in a moment.');
+        return (await ifFree(id, fn));
+    };
+    /**
+     * Writes a booking as it is NOW, with `row` and the prepaid `fields` on top -
+     * never a whole record read before an await (audit P0-A: each of two steps
+     * wrote back what it had read, and the later one undid the earlier).
+     */
+    const patch = (id, row, fields = {}) => {
+        const cur = store.get(id);
+        if (!cur)
+            return undefined;
+        return store.update(id, {
+            ...row,
+            ...(cur.prepaid ? { prepaid: { ...cur.prepaid, ...fields } } : {}),
+        });
+    };
     /** Whether a booking paid in advance still has money work to do. */
-    let ticking = false;
     const moneyPending = (b) => {
         const p = b.prepaid;
         if (!p)
@@ -1799,6 +1891,9 @@ export const createHuazhuHotels = (opts) => {
             return false;
         if (!p.paidAt)
             return false;
+        // Cancelled - at Huazhu's end, say - with nothing decided about the money yet.
+        if (b.status === 'cancelled' && !p.refund && !p.kept && !b.attention)
+            return true;
         // Booked: Huazhu's order number still to be written onto the payment, once.
         if (b.status === 'confirmed' && b.resId && !p.noted && !p.refund && checkout?.annotate)
             return true;
@@ -1822,7 +1917,7 @@ export const createHuazhuHotels = (opts) => {
         if (row.status === 'awaiting-payment') {
             if (!p.sessionId) {
                 if (now() >= p.payBy)
-                    store.update(row.id, { status: 'expired', prepaid: { ...p, lapsedAt: now() } });
+                    patch(row.id, { status: 'expired' }, { lapsedAt: now() });
                 return;
             }
             let state;
@@ -1849,40 +1944,52 @@ export const createHuazhuHotels = (opts) => {
                 const want = row.quote.total;
                 if (!took || took.amountMinor !== want.minor || took.currency !== want.currency) {
                     const said = took ? `${took.amountMinor} ${took.currency}` : 'an amount it could not say';
-                    store.update(row.id, {
-                        status: 'failed',
-                        prepaid: {
-                            ...p,
-                            paidAt: now(),
-                            url: undefined,
-                            refund: {
-                                reason: `the payment page took ${said}, not the ${want.minor} ${want.currency} quoted - nothing was booked`,
-                                at: now(),
-                                tries: 0,
-                            },
+                    // Shown to the guest (`refundReason`): money as `formatMoney` writes
+                    // it, so the card can say it in the guest's own way (香格里拉,
+                    // 2026-10-16) - never minor units.
+                    const shown = took
+                        ? formatMoney(money(took.amountMinor, took.currency))
+                        : 'an amount it could not say';
+                    patch(row.id, { status: 'failed' }, {
+                        paidAt: now(),
+                        url: undefined,
+                        refund: {
+                            reason: `the payment page took ${shown}, not the ${formatMoney(want)} quoted - nothing was booked`,
+                            at: now(),
+                            tries: 0,
                         },
                     });
                     console.error(`[huazhu prepaid ${row.id}] ⚠️ paid ${said} against ${want.minor} ${want.currency} quoted: not booked, refunding`);
                     return;
                 }
-                store.update(row.id, { prepaid: { ...p, paidAt: now(), url: undefined } });
+                patch(row.id, {}, { paidAt: now(), url: undefined });
                 await bookPaid(row.id);
             }
             else if (state === 'closed') {
-                store.update(row.id, {
-                    status: 'expired',
-                    prepaid: { ...p, lapsedAt: now(), url: undefined },
-                });
+                patch(row.id, { status: 'expired' }, { lapsedAt: now(), url: undefined });
             }
             return;
         }
         if (!p.paidAt)
             return;
+        // Cancelled with the money not decided - at Huazhu's end (a lookup or a
+        // follow-up query saw HOTEL_CANCEL): free means all of it back, anything
+        // else a person's to judge (audit P0-B).
+        if (row.status === 'cancelled' && !p.refund && !p.kept) {
+            if (row.attention)
+                return;
+            const at = row.cancelledAt ? Date.parse(row.cancelledAt) : now();
+            const owed = owedOnCancel(row, row.cancellationFee?.minor ?? feeNow(row, at).fee, false);
+            patch(row.id, owed.row, owed.fields);
+            if (owed.fields.refund)
+                await refundOf(row.id, owed.fields.refund.reason);
+            return;
+        }
         // ⚠️ HUAZHU'S ORDER NUMBER ON THE PAYMENT, ONCE (总线程, 2026-10-15), so
         // Stripe's dashboard and Huazhu's order are one look apart. Tried once:
         // a failure is said in the log and never touches the booking.
         if (row.status === 'confirmed' && row.resId && !p.noted && !p.refund && checkout.annotate) {
-            store.update(row.id, { prepaid: { ...p, noted: now() } });
+            patch(row.id, {}, { noted: now() });
             try {
                 await checkout.annotate(p.sessionId ?? '', {
                     huazhu_res_id: row.resId,
@@ -1906,8 +2013,9 @@ export const createHuazhuHotels = (opts) => {
         if (refund?.requestId && !['refunded', 'failed', 'rejected'].includes(refund.status ?? '')) {
             try {
                 const status = await checkout.refundState(refund.requestId);
-                if (status !== refund.status)
-                    store.update(row.id, { prepaid: { ...p, refund: { ...refund, status } } });
+                const latest = store.get(row.id)?.prepaid?.refund;
+                if (latest && status !== latest.status)
+                    patch(row.id, {}, { refund: { ...latest, status } });
                 if ((status === 'failed' || status === 'rejected') && !row.attention) {
                     const why = `refund ${refund.requestId} of gateway session ${p.sessionId} came back ${status}: the guest's money is not back`;
                     store.update(row.id, { attention: why, attentionAt: new Date(now()).toISOString() });
@@ -2294,23 +2402,6 @@ export const createHuazhuHotels = (opts) => {
         }
         return { booked: made.map((b) => publicBooking(store.get(b.id) ?? b)), failed };
     };
-    /**
-     * Waits its turn behind the pass and the landing page - the one at a time
-     * every step on a booking paid in advance takes - then runs.
-     */
-    const inTurn = async (fn) => {
-        for (let i = 0; ticking && i < 400; i += 1)
-            await new Promise((r) => setTimeout(r, 25));
-        if (ticking)
-            throw new Error('A payment here is being settled right now. Ask again in a moment.');
-        ticking = true;
-        try {
-            return await fn();
-        }
-        finally {
-            ticking = false;
-        }
-    };
     /**
      * Pay a booking waiting for payment with UnionPay instead of the card page
      * (robin, 2026-10-15). The card page is closed first - paid on it in the
@@ -2341,6 +2432,16 @@ export const createHuazhuHotels = (opts) => {
         const no = notWaiting(first);
         if (no)
             return no;
+        // ⚠️ COUNTED BEFORE ANYTHING REACHES THE GATEWAY (audit P0-E).
+        const keys = [
+            [`b:${first.id}`, UNIONPAY_ASKS.booking],
+            [`s:${conversationOf(who)}`, UNIONPAY_ASKS.conversation],
+            ...(who.ip ? [[`ip:${who.ip}`, UNIONPAY_ASKS.ip]] : []),
+        ];
+        if (keys.some(([k, most]) => unionPayAsks.count(k) >= most))
+            return refused(`Paying ${first.confirmationCode} with UnionPay was asked for too often this hour. Nothing changed - the card page still takes the payment, or ask again later.`, 'too-many-tries');
+        for (const [k] of keys)
+            unionPayAsks.add(k);
         if (first.prepaid?.method === 'unionpay' && first.prepaid.url)
             return { kind: 'confirm', url: first.prepaid.url, booking: publicBooking(first) };
         let cards;
@@ -2352,15 +2453,22 @@ export const createHuazhuHotels = (opts) => {
         }
         const card = cards[0];
         // No card yet: UnionPay's page to bind one - and nothing else changes.
+        // The same page for half an hour (audit P0-E): asked again, it is handed
+        // out again, not asked of the gateway and UnionPay again.
         if (!card) {
+            const p0 = first.prepaid;
+            if (p0?.enrollUrl && p0.enrollAt !== undefined && now() - p0.enrollAt < ENROLL_REUSE_MS)
+                return { kind: 'enroll', url: p0.enrollUrl };
             try {
-                return { kind: 'enroll', url: (await unionpay.enroll(first.guest.email)).url };
+                const { url } = await unionpay.enroll(first.guest.email);
+                patch(first.id, {}, { enrollUrl: url, enrollAt: now() });
+                return { kind: 'enroll', url };
             }
             catch (err) {
                 return refused(`UnionPay's page for adding a card could not be opened (${err.message}). Nothing changed - ask again.`, 'unreachable');
             }
         }
-        return inTurn(async () => {
+        return inTurnFor(first.id, async () => {
             const row = store.get(first.id) ?? first;
             const again = notWaiting(row);
             if (again)
@@ -2381,7 +2489,7 @@ export const createHuazhuHotels = (opts) => {
                     await settlePrepaid(row);
                     return { kind: 'paid-on-card', booking: publicBooking(store.get(row.id) ?? row) };
                 }
-                store.update(row.id, { prepaid: { ...p, sessionId: undefined, url: undefined } });
+                patch(row.id, {}, { sessionId: undefined, url: undefined });
             }
             const title = row.quote.lines[0]?.title ?? row.hotelName;
             // Prebooked again the way it will be booked: Huazhu's token holds only
@@ -2408,10 +2516,7 @@ export const createHuazhuHotels = (opts) => {
             }
             catch (err) {
                 if (err instanceof HuazhuRefusal) {
-                    store.update(row.id, {
-                        status: 'expired',
-                        prepaid: { ...p, sessionId: undefined, url: undefined, lapsedAt: now() },
-                    });
+                    patch(row.id, { status: 'expired' }, { sessionId: undefined, url: undefined, lapsedAt: now() });
                     const said = refusalCode(err, row.rooms).code;
                     return refused(`Nothing was booked or charged: ${refusalWords(err, `${row.hotelName} - ${title}`, p.currency)}`, said === 'price-changed' || said === 'sold-out' ? said : 'hotel-refused');
                 }
@@ -2437,16 +2542,12 @@ export const createHuazhuHotels = (opts) => {
             catch (err) {
                 return refused(`UnionPay's page could not be opened (${err.message}). Nothing was charged - ask again.`, 'unreachable');
             }
-            const updated = store.update(row.id, {
-                paymentType: 'CCPN',
-                prepaid: {
-                    ...p,
-                    method: 'unionpay',
-                    sessionId: opened.sessionId,
-                    url: opened.url,
-                    ...(token ? { preBookToken: token } : {}),
-                    payBy: now() + payWithin,
-                },
+            const updated = patch(row.id, { paymentType: 'CCPN' }, {
+                method: 'unionpay',
+                sessionId: opened.sessionId,
+                url: opened.url,
+                ...(token ? { preBookToken: token } : {}),
+                payBy: now() + payWithin,
             }) ?? row;
             return { kind: 'confirm', url: opened.url, booking: publicBooking(updated) };
         });
@@ -2500,25 +2601,39 @@ export const createHuazhuHotels = (opts) => {
             return undefined;
         const at = now();
         if (at - (returned.get(sessionId) ?? Number.NEGATIVE_INFINITY) >= 10_000 &&
-            !ticking &&
             moneyPending(found)) {
             returned.set(sessionId, at);
             if (returned.size > 1_000)
                 for (const [k, v] of returned)
                     if (at - v > 10 * 60_000)
                         returned.delete(k);
-            ticking = true;
             try {
-                await settlePrepaid(found);
+                // Under the booking's own lock - taken by the pass meanwhile, this
+                // step is the pass's to take (audit P0-A).
+                await ifFree(found.id, () => settlePrepaid(found));
             }
             catch (err) {
                 console.error(`[huazhu prepaid ${found.id}] the landing page's step failed: ${err.message}`);
             }
-            finally {
-                ticking = false;
-            }
         }
-        return returnOf(store.get(found.id) ?? found);
+        const row = store.get(found.id) ?? found;
+        const told = returnOf(row);
+        // ⚠️ "NOT PAID" ONLY WHEN STRIPE SAYS SO (audit P0-D): a pass busy on this
+        // booking, or behind on others, left a guest who had paid told "nothing
+        // was charged - book again". Not paid here yet, the page is asked - only
+        // read, never moved on.
+        if (told.state === 'not-paid' &&
+            row.status === 'awaiting-payment' &&
+            row.prepaid?.method !== 'unionpay' &&
+            row.prepaid?.sessionId &&
+            checkout) {
+            const page = await checkout.state(row.prepaid.sessionId).catch(() => undefined);
+            if (page === 'paid')
+                return { ...told, state: 'booking' };
+            if (page === undefined)
+                return { ...told, state: 'unknown' };
+        }
+        return told;
     };
     return {
         brand: opts.brand,
@@ -2536,18 +2651,20 @@ export const createHuazhuHotels = (opts) => {
         ...(checkout ? { paymentReturn } : {}),
         ...(checkout && unionpay ? { unionPay } : {}),
         async prepaidTick() {
-            // ⚠️ ONE PASS AT A TIME: a pass slower than the ten seconds between
-            // them would otherwise book a paid stay, or give money back, twice.
-            if (ticking)
+            // ⚠️ EACH BOOKING UNDER ITS OWN LOCK (audit P0-A): two passes, or a
+            // pass and the landing page, never take a step on one booking at once.
+            // One booking's failure holds up none of the others (audit P2).
+            if (closing)
                 return;
-            ticking = true;
-            try {
-                for (const row of store.all())
-                    if (moneyPending(row))
-                        await settlePrepaid(row);
-            }
-            finally {
-                ticking = false;
+            for (const row of store.all()) {
+                if (!moneyPending(row))
+                    continue;
+                try {
+                    await ifFree(row.id, () => settlePrepaid(row));
+                }
+                catch (err) {
+                    console.error(`[huazhu prepaid ${row.id}] the pass's step failed: ${err.message}`);
+                }
             }
         },
         imageDomains() {
@@ -2612,7 +2729,9 @@ export const createHuazhuHotels = (opts) => {
          */
         async drain() {
             closing = true;
-            await Promise.allSettled([...new Set(flights.values())]);
+            // The steps on payments too - a refund or a booking half taken when the
+            // process stopped was lost (audit P1-3, P0-B).
+            await Promise.allSettled([...new Set(flights.values()), ...steps]);
         },
         async searchHotels(q) {
             const terms = (q.query ?? '')
@@ -3222,6 +3341,30 @@ export const createHuazhuHotels = (opts) => {
                 };
             }
             const { fee, forbidden, rule, freeUntil } = feeNow(b);
+            // A test booking says it is one (2026-10-16 audit, P2): Huazhu's test
+            // system charges nobody and books nothing anyone stays in.
+            const testNote = opts.testEnvironment
+                ? " This is a test booking in Huazhu's test system: nothing is charged to anyone."
+                : '';
+            // Paid with UnionPay: Huazhu charged the one-time card, and gives back
+            // to it what its terms allow - nothing passes through here (audit P0-C:
+            // it was told as "paid at the hotel, nothing paid through here").
+            if (b.prepaid?.method === 'unionpay' && b.prepaid.issuedAt) {
+                const back = !forbidden && fee === 0;
+                return {
+                    bookingId: b.id,
+                    confirmationCode: b.confirmationCode,
+                    fee: money(forbidden ? 0 : fee, cur),
+                    refund: back ? b.quote.total : zero,
+                    rule: forbidden
+                        ? `This rate cannot be cancelled now. ${rule} Huazhu keeps the ${formatMoney(b.quote.total)} it charged to the UnionPay card.${testNote}`
+                        : back
+                            ? `${rule} Paid with a UnionPay card that Huazhu charged: cancelling now, Huazhu gives all ${formatMoney(b.quote.total)} back to that same card - not through here.${testNote}`
+                            : `${rule} Paid with a UnionPay card that Huazhu charged: cancelling now gives nothing back - the fee is the whole stay, and Huazhu keeps it.${testNote}`,
+                    ...(freeUntil ? { freeUntil: new Date(freeUntil).toISOString() } : {}),
+                    cancellable: !forbidden,
+                };
+            }
             if (b.prepaid?.paidAt) {
                 // Paid here in advance: free means all of it back, anything else -
                 // the whole stay, on these rates - means none.
@@ -3234,8 +3377,8 @@ export const createHuazhuHotels = (opts) => {
                     rule: forbidden
                         ? `This rate cannot be cancelled now. ${rule} The ${formatMoney(b.quote.total)} paid stays paid.`
                         : back
-                            ? `${rule} Cancelling now gives back all ${formatMoney(b.quote.total)} paid, to the card it was paid with.${opts.sandbox ? ' This is a test booking in the simulated Huazhu, paid in the gateway’s test mode: no real money moves.' : ''}`
-                            : `${rule} Cancelling now gives nothing back: the fee is the whole stay.`,
+                            ? `${rule} Cancelling now gives back all ${formatMoney(b.quote.total)} paid, to the card it was paid with.${opts.sandbox ? ' This is a test booking in the simulated Huazhu, paid in the gateway’s test mode: no real money moves.' : opts.testEnvironment ? ' This is a test booking in Huazhu’s test system, paid in test mode: no real money moves.' : ''}`
+                            : `${rule} Cancelling now gives nothing back: the fee is the whole stay.${testNote}`,
                     ...(freeUntil ? { freeUntil: new Date(freeUntil).toISOString() } : {}),
                     cancellable: !forbidden,
                 };
@@ -3250,7 +3393,9 @@ export const createHuazhuHotels = (opts) => {
                     ? `This rate cannot be cancelled now. ${rule}`
                     : opts.sandbox
                         ? `${rule} This is a test booking in the simulated Huazhu: the fee is worked out as a real booking's would be, and nothing is charged to anyone.`
-                        : `${rule} Nothing was paid through this connector - the booking is paid at the hotel - so any fee is charged under the hotel's terms, and Huazhu works out the exact amount when it cancels.`,
+                        : opts.testEnvironment
+                            ? `${rule} This is a test booking in Huazhu's test system: the fee is worked out as a real booking's would be, and nothing is charged to anyone.`
+                            : `${rule} Nothing was paid through this connector - the booking is paid at the hotel - so any fee is charged under the hotel's terms, and Huazhu works out the exact amount when it cancels.`,
                 ...(freeUntil ? { freeUntil: new Date(freeUntil).toISOString() } : {}),
                 cancellable: !forbidden,
             };
@@ -3259,80 +3404,92 @@ export const createHuazhuHotels = (opts) => {
             const found = findOwn(ref, who);
             if (!found)
                 return null;
-            const b = await refresh(found);
-            // Waiting on UnionPay: a confirmation already made is being booked by
-            // the pass - which alone takes the card, once; one not made never will be.
-            if (b.status === 'awaiting-payment' && b.prepaid?.method === 'unionpay') {
-                const state = b.prepaid.sessionId && unionpay
-                    ? await unionpay.state(b.prepaid.sessionId).catch(() => undefined)
-                    : 'closed';
-                if (state !== 'issued' && state !== undefined) {
-                    return publicBooking(store.update(b.id, {
-                        status: 'expired',
-                        prepaid: { ...b.prepaid, lapsedAt: now(), url: undefined },
-                    }) ?? b);
+            const first = await refresh(found);
+            // A booking paid in advance is cancelled under its own lock - the pass,
+            // the landing page and a switch to UnionPay wait (audit P0-A).
+            const run = async () => {
+                const b = store.get(first.id) ?? first;
+                // Waiting on UnionPay: a confirmation already made is being booked by
+                // the pass - which alone takes the card, once; one not made never will be.
+                if (b.status === 'awaiting-payment' && b.prepaid?.method === 'unionpay') {
+                    const state = b.prepaid.sessionId && unionpay
+                        ? await unionpay.state(b.prepaid.sessionId).catch(() => undefined)
+                        : 'closed';
+                    if (state !== 'issued' && state !== undefined) {
+                        return publicBooking(patch(b.id, { status: 'expired' }, { lapsedAt: now(), url: undefined }) ?? b);
+                    }
+                    throw new Error(state === 'issued'
+                        ? 'The guest has just confirmed on UnionPay, so the stay is being booked with Huazhu now. Ask again in a moment to cancel it.'
+                        : 'UnionPay could not be reached to say whether the guest confirmed. Ask again in a moment - nothing is booked until it can.');
                 }
-                throw new Error(state === 'issued'
-                    ? 'The guest has just confirmed on UnionPay, so the stay is being booked with Huazhu now. Ask again in a moment to cancel it.'
-                    : 'UnionPay could not be reached to say whether the guest confirmed. Ask again in a moment - nothing is booked until it can.');
-            }
-            // Not paid yet: the page is closed, so it cannot be paid after this.
-            if (b.status === 'awaiting-payment' && b.prepaid?.sessionId && checkout) {
-                const state = await checkout.close(b.prepaid.sessionId).catch(() => undefined);
-                if (state === 'closed') {
-                    return publicBooking(store.update(b.id, {
-                        status: 'expired',
-                        prepaid: { ...b.prepaid, lapsedAt: now(), url: undefined },
-                    }) ?? b);
+                // Not paid yet: the page is closed, so it cannot be paid after this.
+                if (b.status === 'awaiting-payment' && b.prepaid?.sessionId && checkout) {
+                    const state = await checkout.close(b.prepaid.sessionId).catch(() => undefined);
+                    if (state === 'closed') {
+                        return publicBooking(patch(b.id, { status: 'expired' }, { lapsedAt: now(), url: undefined }) ?? b);
+                    }
+                    // ⚠️ NO ANSWER IS NOT "PAID" (audit P0-C): the page may well still be
+                    // open and unpaid.
+                    if (state === undefined)
+                        throw new Error('The payment page could not be reached to close it, so nothing was cancelled yet. Ask again in a moment - nothing is booked or charged until the page is paid.');
+                    // Paid in the last second: it is booked now, and cancelled as one.
+                    await settlePrepaid(b);
+                    throw new Error('The guest has just paid, so the stay is being booked with Huazhu now. Ask again in a moment to cancel it - a cancellation in the free period gives all the money back.');
                 }
-                // Paid in the last second: it is booked now, and cancelled as one.
-                await settlePrepaid(b);
-                throw new Error('The guest has just paid, so the stay is being booked with Huazhu now. Ask again in a moment to cancel it - a cancellation in the free period gives all the money back.');
-            }
-            if (b.pendingSince !== undefined || b.status === 'unconfirmed') {
-                throw new Error(waitingWords(b));
-            }
-            if (!b.resId)
-                return publicBooking(b);
-            if (b.status !== 'confirmed')
-                return publicBooking(b);
-            const cur = b.quote.total.currency;
-            try {
-                const out = await client.cancel(b.resId);
-                const fee = typeof out.penaltyAmount === 'number'
-                    ? money(toMinor(out.penaltyAmount, out.penaltyCurrencyCode || cur), out.penaltyCurrencyCode || cur)
-                    : money(feeNow(b).fee, cur);
-                const cancelled = store.update(b.id, {
-                    status: 'cancelled',
-                    hotelStatus: 'HOTEL_CANCEL',
-                    cancelledAt: new Date(now()).toISOString(),
-                    cancellationFee: fee,
-                }) ?? b;
-                // Paid in advance and cancelled free: all of it back. A fee here is
-                // the whole stay (only whole-or-nothing rates are sold this way), so
-                // nothing comes back.
-                if (cancelled.prepaid?.paidAt && fee.minor === 0)
-                    await refundOf(b.id, 'cancelled within the free cancellation period');
-                return publicBooking(store.get(b.id) ?? cancelled);
-            }
-            catch (err) {
-                if (err instanceof HuazhuRefusal && err.code === 5402) {
-                    return publicBooking(store.update(b.id, {
+                if (b.pendingSince !== undefined || b.status === 'unconfirmed') {
+                    throw new Error(waitingWords(b));
+                }
+                if (!b.resId)
+                    return publicBooking(b);
+                if (b.status !== 'confirmed')
+                    return publicBooking(b);
+                const cur = b.quote.total.currency;
+                // ⚠️ THE CANCELLATION AND WHAT IT OWES IN ONE WRITE, then the refund
+                // (audit P0-B) - a process stopped in between leaves the refund to
+                // open, which the pass opens.
+                const cancelled = (fee, at) => {
+                    const latest = store.get(b.id) ?? b;
+                    const owed = owedOnCancel(latest, fee.minor, true);
+                    const done = patch(b.id, {
                         status: 'cancelled',
                         hotelStatus: 'HOTEL_CANCEL',
-                        cancelledAt: b.cancelledAt ?? new Date(now()).toISOString(),
-                    }) ?? b);
-                }
-                if (err instanceof HuazhuRefusal && (err.code === 5401 || err.code === 5405)) {
-                    throw new Error(err.code === 5405
-                        ? 'Huazhu says this stay has already started, so it cannot be cancelled.'
-                        : 'Huazhu says this booking cannot be cancelled.');
+                        cancelledAt: at,
+                        cancellationFee: fee,
+                        ...owed.row,
+                    }, owed.fields) ?? b;
+                    return publicBooking(done);
+                };
+                try {
+                    const out = await client.cancel(b.resId);
+                    const fee = typeof out.penaltyAmount === 'number'
+                        ? money(toMinor(out.penaltyAmount, out.penaltyCurrencyCode || cur), out.penaltyCurrencyCode || cur)
+                        : money(feeNow(b).fee, cur);
+                    cancelled(fee, new Date(now()).toISOString());
                 }
-                if (err instanceof HuazhuUnreachable) {
-                    throw new Error('Huazhu did not answer, so it is not known whether the booking was cancelled. Asking again is safe - cancelling twice does not charge twice.');
+                catch (err) {
+                    if (err instanceof HuazhuRefusal && err.code === 5402) {
+                        // Cancelled already - by this guest's own earlier try whose answer
+                        // was lost, most likely: owed as that cancellation was (audit P0-B).
+                        cancelled(b.cancellationFee ?? money(feeNow(b).fee, cur), b.cancelledAt ?? new Date(now()).toISOString());
+                    }
+                    else if (err instanceof HuazhuRefusal && (err.code === 5401 || err.code === 5405)) {
+                        throw new Error(err.code === 5405
+                            ? 'Huazhu says this stay has already started, so it cannot be cancelled.'
+                            : 'Huazhu says this booking cannot be cancelled.');
+                    }
+                    else if (err instanceof HuazhuUnreachable) {
+                        throw new Error('Huazhu did not answer, so it is not known whether the booking was cancelled. Asking again is safe - cancelling twice does not charge twice.');
+                    }
+                    else
+                        throw err;
                 }
-                throw err;
-            }
+                const after = store.get(b.id);
+                const refund = after?.prepaid?.refund;
+                if (refund && !refund.requestId)
+                    await refundOf(b.id, refund.reason);
+                return publicBooking(store.get(b.id) ?? after ?? b);
+            };
+            return first.prepaid ? inTurnFor(first.id, run) : run();
         },
         async policies() {
             // Huazhu publishes no policy text: each RATE carries its terms, and those