@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/_internal/server/features/checkout/actions.js

@@ -13,10 +13,9 @@ import { ApiError, ValidationError, NotFoundError, ERROR_MESSAGES } from "../../
 import { ORDER_FIELDS } from "../../../../constants/field-names.js";
 import { serverLogger } from "../../../../monitoring/index.js";
 import { roundShippingUp, } from "../../../shared/shipping/quote.js";
-import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
-import { maxRedeemablePoints } from "../../../../features/points/schemas/firestore.js";
 import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories/index.js";
 import { isIntraStateSupply } from "../../../shared/fees/calculator.js";
+import { resolveStateKey, INDIA_STATES } from "../../../shared/fees/india-states.js";
 import { computePreOrderDepositAmount, lineTotalFor, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
 import { COD_MAX_ORDER_VALUE_FALLBACK } from "../../../../features/admin/schemas/firestore.js";
 import { CHECKOUT_ERROR_CODES } from "../../../../errors/error-codes.js";
@@ -24,10 +23,17 @@ import { failedCheckoutRepository } from "../../../../features/checkout/reposito
 import { sendOrderConfirmationEmail } from "../../../../features/contact/server.js";
 import { splitCartIntoOrderGroups } from "../../../../features/orders/index.js";
 import { DEFAULT_STORE_SHIPPING_POLICY, quoteShipping, toStoreShippingPolicy, } from "../../../shared/features/shipping/mode.js";
+/*
+ * D44's first consumer of `shippingUnavailable`. A store whose shipping cannot
+ * be priced is a configuration fault with a money consequence — we ship free —
+ * so it belongs in the operator queue, keyed on the store so a hundred
+ * checkouts produce one case.
+ */
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
 import { computeProtectionFees } from "../../../shared/features/shipping/protections.js";
 import { resolveCouponCategorySlugs } from "../../../../features/promotions/actions/coupon-actions.js";
 import { assertCheckoutLane, assertLockedLinesStillValid, finalizeLockedLines, } from "./locked-lines.js";
-import { activeLane, defaultCheckoutItems, laneOf, } from "../../../shared/checkout/lanes.js";
+import { activeLane, defaultCheckoutItems, resolveCheckoutItems, laneOf, } from "../../../shared/checkout/lanes.js";
 import { computeCodHandlingFee, computeGiftWrapFee, computeShipmentProtectionFee, computeSaleProtectionFee, computeCheckoutFees, allocateCheckoutFees, } from "../../../shared/fees/calculator.js";
 import { getAdminDb, getAdminRealtimeDb, RTDB_PATHS, } from "../../../../providers/db-firebase/index.js";
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION } from "../../../../features/products/schemas/firestore.js";
@@ -51,6 +57,10 @@ import { checkEmiEligibility, computeBuyerEmiQuote, computeEmiSchedule } from ".
 import { formatShippingAddress } from "./data.js";
 import { enforceMaxPerUserForCart } from "./prize-bundle-gates.js";
 import { getListingRule, runSyncPreflight, assertPaymentMethodAllowed, } from "../../../shared/checkout/rules/index.js";
+// The `GroupCouponDiscountResult` type is deliberately NOT imported: every
+// call site here destructures the result inline, so naming the type would be
+// an unused import.
+import { computeCartCouponDiscount, computeGroupCouponDiscount, } from "../../../shared/checkout/coupon-discount.js";
 import { revalidateGroupLines } from "./group-rule-revalidation.js";
 import { cartIsDigitalOnly } from "../../../shared/listing-types/cart-shipping.js";
 import { processRefundAction } from "../refunds/actions.js";
@@ -60,6 +70,22 @@ import { resolveSupplierIdentity } from "./supplier-identity.js";
 import { PAYMENT_WINDOW_MS } from "../../../../features/orders/constants/payment-window.js";
 import { isCheckoutValueOtpVerified } from "../../../../features/checkout/actions/checkout-value-otp-actions.js";
 const AUDIT_LOG_FAIL_MSG = "checkout: audit log failed (non-critical)";
+/**
+ * How long a `gatewayOrderClaims` holder owns the right to place an order
+ * before another caller may take the claim over.
+ *
+ * 🛑 Sized against the SLOWEST legitimate placement, not the typical one. The
+ * route runs with `maxDuration = 60`, and a placement fans out to the gateway
+ * re-fetch, the cart read, product validation, stock decrements and N order
+ * writes — so a lease shorter than the work would let a second placer start
+ * while the first is still mid-write, which is the duplicate order the claim
+ * exists to prevent. 90s is that ceiling plus headroom.
+ *
+ * It is also the buyer's worst-case wait before a retry can succeed, which is
+ * the other reason not to make it generous: before this existed the wait was
+ * unbounded, because a failed placement left the claim forever.
+ */
+const GATEWAY_CLAIM_LEASE_MS = 90000;
 /**
  * SB-UNI-N — Atomically claim the next available digital code for a confirmed
  * order. Pre-fetches a candidate code outside the transaction then locks and
@@ -196,7 +222,37 @@ function accumulateCouponUsage(accumulator, couponCode, couponId, discountAmount
  * exact same per-seller shipping fee that order creation charges/records —
  * a single source of truth instead of a third re-implementation.
  */
-export async function resolveShippingCost(storeId) {
+export async function resolveShippingCost(storeId, 
+/**
+ * The cart facts needed to QUOTE rather than merely resolve the policy.
+ *
+ * 🛑 D44 — OMITTING THIS IS TWO MONEY BUGS IN OPPOSITE DIRECTIONS, and until
+ * now every one of the five call sites omitted it.
+ *
+ * `quoteShipping` was called exactly once, here, with `goodsValue: 0` and
+ * `carrierRate: null`. Measured against its own logic
+ * (`shared/features/shipping/mode.ts`):
+ *
+ * 1. **Free-above-threshold can never fire.** The test is
+ *    `goodsValue >= policy.freeAbove`, and `0 >= 999` is false for any
+ *    positive threshold — so a store advertising "free shipping over ₹999"
+ *    **charged its base rate on a ₹5,000 order.** The buyer is OVERCHARGED,
+ *    and the seller's own offer silently does not exist.
+ * 2. **`estimate` mode ships FREE.** No carrier rate returns
+ *    `kind: "unavailable"`, which the mapping below turns into
+ *    `shippingFee: 0` — and `shippingUnavailable` had **zero consumers**, so
+ *    nobody noticed. The platform/seller is UNDERCHARGED, which is what that
+ *    field's own 🛑 warns about: "a zero there would ship every parcel free
+ *    at our expense, silently, until somebody noticed."
+ *
+ * `flat` and `free` modes were unaffected, which is why this survived: the
+ * common cases are correct and only a store with a threshold or an estimate
+ * policy is mispriced.
+ *
+ * Still optional, because the one legitimate caller is the seller-settings
+ * surface that wants the POLICY and has no cart. Every money path passes it.
+ */
+opts) {
     if (!storeId) {
         return {
             shippingFee: 0,
@@ -214,7 +270,11 @@ export async function resolveShippingCost(storeId) {
     const store = await storeRepository.findById(storeId);
     const storeOwnerId = store?.ownerId;
     const storeEmiEnabled = store?.emiEnabled === true;
-    const storeState = await resolveStoreState(storeId);
+    // `store` is passed in rather than re-fetched inside: G3 needs its `gstin`,
+    // and the document is already in hand one line above. A second
+    // `storeRepository` read here is what line ~504's comment warns against,
+    // and it would cost a Firestore read on every checkout (Rule #6).
+    const storeState = await resolveStoreState(storeId, store?.gstin);
     /*
      * ── C5b: the store's shipping MODE, not a flat number ──────────────────
      *
@@ -240,17 +300,76 @@ export async function resolveShippingCost(storeId) {
         ? toStoreShippingPolicy(store.shippingPricing)
         : await legacyFlatPolicy(storeOwnerId);
     /*
-     * 🛑 `goodsValue: 0` and no carrier rate here, deliberately.
-     *
-     * This function resolves the POLICY; it does not know the cart. A caller
-     * that needs the charged amount calls `quoteShipping` with the group's goods
-     * value and, for `estimate` mode, a rate — and `shippingFee` below stays the
-     * non-carrier answer so every existing caller behaves exactly as before
-     * until it is converted. An `estimate`-mode store therefore reports
-     * `shippingUnavailable`, which is the signal to go and get a rate rather
-     * than a zero that would ship for free at our expense.
+     * 🛑 D44 FIXED HERE: the quote now uses the caller's real goods value.
+     *
+     * This comment used to read *"`goodsValue: 0` and no carrier rate here,
+     * deliberately… a caller that needs the charged amount calls `quoteShipping`
+     * with the group's goods value"*. The design was right and **no caller ever
+     * did it** — `quoteShipping` had exactly one call site, this one, and all
+     * five callers destructured `shippingFee` and ignored both `shippingPolicy`
+     * and `shippingUnavailable`. A seam nobody used is not a seam; it is a
+     * default, and this default mispriced two policy shapes (see the `opts`
+     * docstring above).
+     *
+     * Defaulting `goodsValue` to 0 keeps the policy-only callers behaving
+     * exactly as before, so this is additive for them and corrective for the
+     * money paths.
      */
-    const quote = quoteShipping({ policy, goodsValue: 0, carrierRate: null });
+    const quote = quoteShipping({
+        policy,
+        goodsValue: opts?.goodsValue ?? 0,
+        carrierRate: opts?.carrierRate ?? null,
+    });
+    /*
+     * ── D44, the other half: `shippingUnavailable` gets its FIRST CONSUMER ────
+     *
+     * The field was declared, assigned twice, and read by nothing — its own 🛑
+     * said "the caller MUST act on this rather than trusting `shippingFee: 0`"
+     * and no caller did. So an `estimate`-mode store shipped every parcel free.
+     *
+     * 🛑 IT DOES NOT REFUSE THE CHECKOUT, and that is a deliberate choice rather
+     * than timidity. **There is no carrier-rate source in the system at all**:
+     * Shiprocket is authenticated but its create-order/AWB/rate calls are
+     * unverified with zero callers, so `carrierRate` can only ever be null today.
+     * Throwing here would therefore break checkout for every estimate-mode store
+     * outright — converting a silent revenue leak into a total outage for those
+     * sellers, which is the worse of the two.
+     *
+     * So the leak is made VISIBLE instead: one case per store (the dedupe key is
+     * the store, so a hundred checkouts produce one row), carrying the amount we
+     * failed to charge. Once somebody has measured how many stores are actually
+     * in `estimate` mode, refusing becomes the correct stricter behaviour — and
+     * that measurement is a one-line query, not a design question.
+     *
+     * Fire-and-forget: a case write must never fail the checkout it is
+     * reporting on.
+     */
+    if (quote.kind === "unavailable" && opts?.goodsValue !== undefined) {
+        void paymentCasesRepository()
+            .openOrObserve({
+            kind: "shipping_unpriced",
+            subjectId: storeId,
+            severity: "warning",
+            title: `Shipping could not be priced — ${storeId} is shipping free`,
+            detail: [
+                `This store's shipping policy is \`estimate\` mode and no carrier rate`,
+                `was available, so the quote came back "unavailable" and the checkout`,
+                `charged ₹0 for shipping.`,
+                "",
+                `Store: ${storeId}`,
+                `Goods value on this order group: ${opts.goodsValue}`,
+                "",
+                `🛑 There is no carrier-rate integration wired, so this will recur for`,
+                `every order from this store. Fix by giving the store a \`flat\` or`,
+                `\`free\` policy in its shipping settings, or by wiring a rate source.`,
+            ].join("\n"),
+            entityType: "store",
+            entityId: storeId,
+        })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+    }
     return {
         shippingFee: quote.kind === "charge" ? quote.amount : 0,
         storeOwnerId: storeOwnerId ?? undefined,
@@ -302,60 +421,50 @@ async function legacyFlatPolicy(storeOwnerId) {
     return { mode: { kind: "flat", amount } };
 }
 /** P-8 GST — the seller's registered/pickup state, used to determine intra- vs inter-state tax. */
-async function resolveStoreState(storeId) {
+async function resolveStoreState(storeId, 
+/**
+ * The store's GSTIN, supplied by the caller which already holds the store
+ * document. Not re-fetched here — see the call site.
+ */
+storeGstin) {
+    /*
+     * ── G3: the GSTIN's state code wins over the typed pickup address ────────
+     *
+     * A GSTIN's first two characters ARE the state of registration — it is
+     * issued per state, so for a registered seller it is the authoritative
+     * place of supply. The pickup address is free text a seller typed, and a
+     * store whose pickup state disagrees with its GSTIN prefix (a warehouse in
+     * another state, a typo, a seller who moved) splits the tax on the wrong
+     * one.
+     *
+     * `resolveStateKey` accepts a bare code, a full GSTIN, or a name, so the
+     * GSTIN goes to it whole rather than being sliced here — that keeps the
+     * "first two characters are the state" knowledge in exactly one place.
+     *
+     * 🛑 Falls back to the pickup address rather than failing: an UNREGISTERED
+     * seller legitimately has no GSTIN and is the common case on this platform.
+     * Returns the canonical display NAME, not the raw code, so every downstream
+     * reader still receives a state name.
+     */
+    const fromGstin = resolveStateKey(storeGstin);
+    if (fromGstin)
+        return INDIA_STATES[fromGstin].name;
     const addresses = await addressesRepository.listByOwner("store", storeId);
     const pickup = addresses.find((a) => a.isDefault) ?? addresses[0];
     return pickup?.state;
 }
-/**
- * Prorates every buyer-applied coupon against one seller-group's total. Pure
- * — no side effects (usage-accumulator bookkeeping is layered on by callers
- * that actually place an order). Shared by createOrderForGroup,
- * createPhonePeGroupOrder, and the read-only previewCheckoutPricing so the
- * three can never drift on how a coupon splits across sellers (was three
- * near-identical copies before this extraction — Duplication Decision
- * Framework's Rule of Three).
+/*
+ * 🛑 `computeGroupCouponDiscount` and `GroupCouponDiscountResult` MOVED to
+ * `_internal/shared/checkout/coupon-discount.ts` on 2026-10-21. Imported at
+ * the top of this file; do not re-add a local copy.
+ *
+ * It was module-private here, which meant the three order paths in this file
+ * could reach it and `/api/payment/create-order` — the route that decides what
+ * the buyer's CARD is charged — could not, because a consumer route cannot
+ * deep-import `_internal/server`. That route consequently had no coupon term at
+ * all, so every coupon order paid by card over-captured by the discount. One
+ * implementation, four callers.
  */
-function computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, storeId) {
-    let couponDiscount = 0;
-    const appliedDiscounts = [];
-    for (const coupon of appliedCoupons) {
-        let couponGroupDiscount = 0;
-        const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
-        if (isSellerScoped) {
-            if (coupon.storeId !== storeId)
-                continue;
-            if (coupon.applicableItemIds?.length) {
-                const eligibleTotal = groupLines
-                    .filter((l) => coupon.applicableItemIds.includes(l.itemId))
-                    .reduce((s, l) => s + l.lineTotal, 0);
-                couponGroupDiscount =
-                    eligibleTotal > 0
-                        ? Math.min(roundRupees((eligibleTotal / groupTotal) * coupon.discountAmount), eligibleTotal)
-                        : 0;
-            }
-            else {
-                couponGroupDiscount = Math.min(coupon.discountAmount, groupTotal);
-            }
-        }
-        else if (cartSubtotal > 0) {
-            couponGroupDiscount = Math.min(roundRupees((groupTotal / cartSubtotal) * coupon.discountAmount), groupTotal);
-        }
-        if (couponGroupDiscount > 0) {
-            couponDiscount += couponGroupDiscount;
-            appliedDiscounts.push({
-                code: coupon.code,
-                couponId: coupon.couponId,
-                type: "coupon",
-                discountAmount: couponGroupDiscount,
-                scope: coupon.scope,
-                storeId: coupon.storeId,
-            });
-        }
-    }
-    couponDiscount = Math.min(couponDiscount, groupTotal);
-    return { couponDiscount, appliedDiscounts };
-}
 function buildStockUpdatePayload(product, qtyDelta) {
     const lt = (product.listingType ?? "standard");
     const rule = getListingRule(lt);
@@ -500,6 +609,29 @@ async function createOrderForGroup(group, orderType, ctx) {
     const { giftWrapAddon = false, giftWrapMessage, shipmentProtectionAddon = false, saleProtectionAddon = false, } = storeAddons?.[firstItem.storeId] ?? {};
     const { platformFee = 0, gstOnFee: platformFeeGst = 0 } = platformFeeByStore.get(firstItem.storeId) ?? {};
     const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
+    /*
+     * ── G1: the discount is computed HERE, before the GST, on purpose ────────
+     *
+     * This used to sit ~150 lines below, after `sumGroupGst` had already backed
+     * the tax out of the UNDISCOUNTED gross — so the order recorded tax on money
+     * the buyer never paid (₹30.51 on a ₹1,000 item with a ₹200 coupon at 18%,
+     * verified).
+     *
+     * A discount shown on the invoice generally reduces the value of supply, so
+     * the pipeline order has to be goods → discount → tax, and that makes the
+     * computation's POSITION load-bearing rather than incidental. Moved up
+     * rather than duplicated: it is pure (no Firestore, no side effects — the
+     * usage-accumulator bookkeeping is layered on separately below), so hoisting
+     * it changes nothing but the order of two pure steps.
+     *
+     * 🛑 Do not move `sumGroupGst` above this, and do not recompute the discount
+     * below. Both re-open the defect.
+     */
+    const groupLines = group.map(({ item, product }) => ({
+        itemId: item.itemId,
+        lineTotal: lineTotalFor(item, product),
+    }));
+    const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     // A multi-member line expands into one row PER MEMBER sharing a groupSlug, so
     // each row carries its own HSN/GST and can be cancelled independently; the
@@ -510,7 +642,15 @@ async function createOrderForGroup(group, orderType, ctx) {
         return expandCartLineToOrderRows(item, product, ctx.productById).map((baseLine) => itemRule.decorateOrderItem(baseLine, product));
     });
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
-    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId);
+    /*
+     * D44: the group's real goods value, so free-above-threshold can fire.
+     *
+     * `lineTotalFor`, never `item.price * item.quantity` — that is the
+     * hand-rolled rule Root Cause #75 is about, and on a locked-price or
+     * grouped line the two differ.
+     */
+    const groupGoodsValue = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
+    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupGoodsValue });
     /*
      * 🛑 The buyer's quote WINS over the seller's configured rate, and it is
      * re-rounded here rather than trusted as sent.
@@ -543,50 +683,22 @@ async function createOrderForGroup(group, orderType, ctx) {
     // then split the group total into a single cgst/sgst/igst breakdown for the
     // order document. Skipped entirely when GST is off or the buyer's state is
     // unknown (digital-only carts have no shipping address).
-    let gstBreakdown;
-    if (gstSettings?.enabled && buyerState) {
-        /*
-         * 🛑 `isIntraStateSupply`, not `storeState === buyerState`. That raw
-         * comparison read "Karnataka" / "karnataka" / "KA" as three different
-         * states — the exact drift `constants/geo/subdivisions.ts` opens by
-         * documenting — and a store with no address resolved to `false`, i.e.
-         * silently inter-state. `null` means "cannot tell" and is logged rather
-         * than guessed; the AMOUNT is identical either way (IGST total ==
-         * CGST+SGST total), so what was wrong was the split on the invoice.
-         */
-        const intra = isIntraStateSupply(storeState, buyerState);
-        if (intra === null) {
-            serverLogger.warn("[gst] place of supply undetermined — defaulting to inter-state (IGST)", { storeId: firstItem.storeId, hasStoreState: !!storeState });
-        }
-        // Per-member, not per-line: a bundle or grouped line spans several products
-        // with several different rates, and taxing the whole line at one product's
-        // rate is wrong in both directions. Shared with previewCheckoutPricing so
-        // the figure shown and the figure charged cannot drift.
-        const summary = sumGroupGst(group.map(({ item }) => item), ctx.productById, intra ?? false);
-        /*
-         * The split is taken AS COMPUTED, per slice, by `calculateGst` inside
-         * `sumGroupGst`. It used to be re-derived here as
-         * `Math.round(gstAmount / 2)` — whole rupees, so ₹161.82 became
-         * 81.00/80.82 rather than 80.91/80.91, and a ₹0.52 total rounded to 0 and
-         * was then dropped off the invoice entirely by the `|| undefined` below.
-         *
-         * The guard is on EITHER base: an order of purely exempt goods has a real
-         * taxable value to report and zero tax, and skipping it left the invoice
-         * unable to reconcile.
-         */
-        if (summary.taxableAmount > 0 || summary.exemptAmount > 0) {
-            gstBreakdown = summary;
-        }
-    }
     const isCodLike = paymentMethod === "cod" || paymentMethod === "upi_manual" || paymentMethod === "cash";
-    const depositAmount = !isCodLike
-        ? undefined
-        : orderType === "preorder"
-            ? computePreOrderDepositAmount(group, commissions.codDepositPercent)
-            : roundRupees(groupTotal * (commissions.codDepositPercent / 100));
-    const codRemainingAmount = isCodLike
-        ? roundRupees(groupTotal - (depositAmount ?? 0))
-        : undefined;
+    /*
+     * 🛑 D43 — THE DEPOSIT/REMAINING SPLIT MOVED DOWN, BELOW `orderTotal`.
+     *
+     * It used to be computed HERE, on `groupTotal` — the goods value — so
+     * `depositAmount + codRemainingAmount` summed to the goods only and omitted
+     * shipping, the COD handling fee, add-ons, the platform fee and its GST.
+     * A COD buyer was told to "pay ₹X on delivery" where X was short by every
+     * fee they had just agreed to, and the courier would collect the wrong
+     * amount.
+     *
+     * It could not be fixed in place: `codHandlingFee` (below), `giftWrapFee`
+     * and both protection fees are all computed AFTER this point, so the total
+     * simply did not exist yet. The split now sits immediately after
+     * `orderTotal`, which is the only place every term is known.
+     */
     let emiSchedule;
     if (paymentMethod === "emi" && emiTenureMonths) {
         const eligibility = checkEmiEligibility(groupTotal, storeEmiEnabled, emiSettings);
@@ -626,9 +738,80 @@ async function createOrderForGroup(group, orderType, ctx) {
         shippingFee: (s, sel) => computeShipmentProtectionFee(s, sel, commissions),
         saleFee: (s, sel) => computeSaleProtectionFee(s, sel, commissions),
     });
+    /*
+     * 🛑 THIS BLOCK WAS MOVED DOWN (2026-10-21) and its position is load-bearing.
+     *
+     * It used to sit ~90 lines above, before `codHandlingFee`, `giftWrapFee` and
+     * the two protection fees were computed — so it could not possibly tax them,
+     * and they entered the order total as bare addends carrying no tax (G5).
+     *
+     * It now runs after every ancillary charge is known and before `orderTotal`
+     * consumes them. Do not move it back up, and do not move a fee computation
+     * below it.
+     */
+    let gstBreakdown;
+    if (gstSettings?.enabled && buyerState) {
+        /*
+         * 🛑 `isIntraStateSupply`, not `storeState === buyerState`. That raw
+         * comparison read "Karnataka" / "karnataka" / "KA" as three different
+         * states — the exact drift `constants/geo/subdivisions.ts` opens by
+         * documenting — and a store with no address resolved to `false`, i.e.
+         * silently inter-state. `null` means "cannot tell" and is logged rather
+         * than guessed; the AMOUNT is identical either way (IGST total ==
+         * CGST+SGST total), so what was wrong was the split on the invoice.
+         */
+        const intra = isIntraStateSupply(storeState, buyerState);
+        if (intra === null) {
+            serverLogger.warn("[gst] place of supply undetermined — defaulting to inter-state (IGST)", { storeId: firstItem.storeId, hasStoreState: !!storeState });
+        }
+        // Per-member, not per-line: a bundle or grouped line spans several products
+        // with several different rates, and taxing the whole line at one product's
+        // rate is wrong in both directions. Shared with previewCheckoutPricing so
+        // the figure shown and the figure charged cannot drift.
+        const summary = sumGroupGst(group.map(({ item }) => item), ctx.productById, intra ?? false, 
+        // G1 — the taxable value is the POST-discount gross. See the hoist above.
+        couponDiscount, 
+        /*
+         * G5 — the ancillary charges, taxed at the principal rate. Shipping,
+         * COD handling, gift wrap and both protections; NOT the platform fee,
+         * which already carries its own `platformFeeGst` and would be taxed
+         * twice, and NOT the EMI surcharge, which is a financing charge with
+         * its own treatment and is deliberately outside the decided scope.
+         */
+        roundRupees(shippingFee + codHandlingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee));
+        /*
+         * The split is taken AS COMPUTED, per slice, by `calculateGst` inside
+         * `sumGroupGst`. It used to be re-derived here as
+         * `Math.round(gstAmount / 2)` — whole rupees, so ₹161.82 became
+         * 81.00/80.82 rather than 80.91/80.91, and a ₹0.52 total rounded to 0 and
+         * was then dropped off the invoice entirely by the `|| undefined` below.
+         *
+         * The guard is on EITHER base: an order of purely exempt goods has a real
+         * taxable value to report and zero tax, and skipping it left the invoice
+         * unable to reconcile.
+         */
+        if (summary.taxableAmount > 0 || summary.exemptAmount > 0) {
+            gstBreakdown = summary;
+        }
+    }
     const groupCouponCodes = new Set();
-    const groupLines = group.map(({ item }) => ({ itemId: item.itemId, lineTotal: item.price * item.quantity }));
-    const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
+    /*
+     * 🛑 `couponDiscount` / `appliedDiscounts` are HOISTED to just after
+     * `groupTotal` (~line 860), not computed here. The move is load-bearing:
+     * `sumGroupGst` sits between the two and now takes the discount, because the
+     * taxable value is the post-discount gross (G1). Recomputing here would be a
+     * second copy; moving the GST call below this would re-open the defect.
+     *
+     * What REMAINS here is the side effect — accumulating coupon usage — which
+     * must stay where it is, after the group has been confirmed placeable.
+     *
+     * Also fixed in the hoist: `groupLines` was built with
+     * `item.price * item.quantity` while `groupTotal` (155 lines above, same
+     * function) used `lineTotalFor`, and `computeGroupCouponDiscount` divides one
+     * by the other — so on a locked-price line the numerator carried the LIST
+     * price and the denominator the AGREED one, the ratio exceeded 1, and the
+     * coupon over-discounted that group. Root Cause #75, sixth copy.
+     */
     for (const discount of appliedDiscounts) {
         if (discount.couponId) {
             accumulateCouponUsage(couponUsageAccumulator, discount.code, discount.couponId, discount.discountAmount);
@@ -650,7 +833,49 @@ async function createOrderForGroup(group, orderType, ctx) {
      * OUR service fee to the seller, charged to the buyer on top of the fee —
      * not tax on the goods.
      */
-    Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0);
+    /*
+     * 🛑 D42 — ROUNDED ONCE, HERE, AT THE END.
+     *
+     * This was a raw float sum of nine 2dp terms written verbatim to
+     * Firestore. IEEE-754 does not represent 0.1 exactly, so a nine-term sum
+     * lands on values like 1011.8000000000001 — and that is what got stored as
+     * the order's total, rendered on the invoice, and compared against the
+     * captured amount. The capture route was saved only because
+     * `rupeesToPaise` rounds on the way to the gateway; the Firestore write had
+     * no such protection.
+     *
+     * Rounded ONCE on the sum, never per term: rounding each addend first
+     * compounds nine half-paisa errors instead of one, which is how a total
+     * drifts from the sum of the lines shown beside it.
+     */
+    roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0));
+    /*
+     * ── D43: the COD deposit/remaining split, on the ORDER TOTAL ──────────────
+     *
+     * Moved here from ~150 lines above, where it was computed on `groupTotal`
+     * and therefore summed to the goods value alone — see the 🛑 at its old
+     * site. Every term `orderTotal` needs is finally known at this point, which
+     * is why this is the only correct home for it.
+     *
+     * 🛑 The pre-order branch is deliberately left on `group`:
+     * `computePreOrderDepositAmount` reads each line's own
+     * `preOrderDepositPercent`, because a pre-order deposit is a per-PRODUCT
+     * commercial term the seller set, not a percentage of the order. Rebasing it
+     * on `orderTotal` would silently change what every existing pre-order
+     * charges — a different defect, not this one.
+     *
+     * `roundRupees` on both halves, and the remainder is taken as
+     * `orderTotal − deposit` rather than independently rounded, so the two
+     * provably sum to the total instead of drifting by a paisa (D42's shape).
+     */
+    const depositAmount = !isCodLike
+        ? undefined
+        : orderType === "preorder"
+            ? computePreOrderDepositAmount(group, commissions.codDepositPercent)
+            : roundRupees(orderTotal * (commissions.codDepositPercent / 100));
+    const codRemainingAmount = isCodLike
+        ? roundRupees(orderTotal - (depositAmount ?? 0))
+        : undefined;
     const imageUrls = [
         ...new Set(group
             .map(({ product }) => product.mainImage)
@@ -729,6 +954,16 @@ async function createOrderForGroup(group, orderType, ctx) {
         // This group's pro-rata share of the checkout's single capped commission —
         // the shares across a multi-store checkout sum to exactly what was charged.
         platformFee: !adminBypass && platformFee > 0 ? platformFee : undefined,
+        /*
+         * Persisted alongside the fee, 2026-10-21. It was computed here, charged
+         * to the buyer as its own term in `orderTotal`, and then folded into
+         * `gstAmount` — so no field held the fee's own tax and a refund had to
+         * re-derive it from live percentages, which is how D32's ~10x
+         * over-deduction happened. The note above this function's `orderTotal`
+         * already explains why the two are kept separate; this persists the second
+         * one so a later reader does not have to reconstruct it.
+         */
+        platformFeeGst: !adminBypass && platformFeeGst > 0 ? platformFeeGst : undefined,
         giftWrapAddon: !adminBypass && giftWrapFee > 0 ? true : undefined,
         giftWrapFee: !adminBypass && giftWrapFee > 0 ? giftWrapFee : undefined,
         giftWrapMessage: !adminBypass && giftWrapFee > 0 ? giftWrapMessage?.slice(0, 500) : undefined,
@@ -782,6 +1017,14 @@ async function createOrderForGroup(group, orderType, ctx) {
         emiTenureMonths: !adminBypass && emiSchedule ? emiTenureMonths : undefined,
         emiTokenAmount: !adminBypass ? emiSchedule?.tokenAmount : undefined,
         emiSurchargeAmount: !adminBypass ? emiSchedule?.surchargeAmount : undefined,
+        /*
+         * D45: the seller's share of the surcharge, recorded for the first time.
+         * `computeEmiSchedule` has always returned it and nothing ever stored it,
+         * so a split the admin had configured (default 50%) was computed and
+         * discarded on every EMI order. Persisting it moves no money — see the
+         * field's own 🛑 — it just stops the decision being thrown away.
+         */
+        emiSurchargeSellerShare: !adminBypass ? emiSchedule?.surchargeSellerShare : undefined,
         emiInstallments: !adminBypass && emiSchedule
             ? emiSchedule.installments.map((i) => ({ index: i.index, dueDate: i.dueDate, amount: i.amount, status: "pending" }))
             : undefined,
@@ -1178,45 +1421,46 @@ export async function createCheckoutOrderAction(input) {
     }
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);
     /*
-     * Spend points AFTER the orders exist.
-     *
-     * 🛑 This ordering is the whole safety argument. Redeeming first and then
-     * failing to create an order would debit a buyer for something they never
-     * received, and points have no refund path that does not need a human. This
-     * way the worst case is an order placed at full price with the balance
-     * intact — recoverable, and visible to the buyer, who still has their
-     * points.
-     *
-     * The amount is re-derived server-side against the real total rather than
-     * taken from the request; `maxRedeemablePoints` applies the 50% cap, and
-     * `redeem` re-checks the balance inside its own transaction.
+     * ── 🛑 THE POINTS REDEMPTION BLOCK WAS DELETED HERE, 2026-10-21 (D46) ─────
+     *
+     * It debited the buyer's points and reduced NOTHING, and its own comment
+     * asserted the opposite. Preserved verbatim because the reasoning error is
+     * the instructive part:
+     *
+     *     "This ordering is the whole safety argument. … This way the worst case
+     *      is an order placed at full price with the balance intact."
+     *
+     * The balance was not intact. It was debited. That sentence reasons only
+     * about the branch where `redeem` THROWS — in which case, yes, the buyer
+     * keeps their points. The SUCCESS branch is the broken one: by the time this
+     * ran, `createOrderForGroup` had already created every order and the gateway
+     * had already captured `total`, so a successful redeem took points from a
+     * buyer who had just paid full price. No order field, no cart field and no
+     * gateway amount was ever reduced by `spend`.
+     *
+     * 🛑 It was unreachable, and that is the only reason it cost nothing: no
+     * route schema, no caller and no UI ever passed `pointsToRedeem` — verified
+     * across `src/` and `appkit/src/`. So the hazard was not the behaviour, it
+     * was that ADDING ONE FIELD to one route schema would have made it live,
+     * while `UserPointsView` already promises buyers "up to half of an order's
+     * total can be paid with points". Somebody would have wired it.
+     *
+     * Deleting it leaves a promise with no mechanism, which is a disappointment.
+     * Keeping it left a mechanism that silently takes points, which is a theft.
+     *
+     * ## What the real tender has to do instead
+     *
+     * Points are a TENDER, so they belong in the pricing pipeline, not after it:
+     * a stage in `computeCheckoutTotal` AFTER rounding — `amountDue = total −
+     * pointsApplied` — with the gateway capturing `amountDue` and the
+     * post-capture guard comparing against `amountDue`. Anything else makes
+     * points a sixth way the captured amount can diverge from the recorded order
+     * total, which is the D37/D38/D40 family this plan exists to close.
+     *
+     * Everything that work needs now exists: `purchase_earn`, per-batch expiry,
+     * FIFO consumption, `redemption_reversal` and the seller-funded deduction.
+     * What is missing is the pipeline stage and the two document fields.
      */
-    if (input.pointsToRedeem && input.pointsToRedeem > 0 && orderIds.length > 0) {
-        try {
-            const balance = await pointsRepository.getBalance(uid);
-            const spend = maxRedeemablePoints(total, Math.min(balance, input.pointsToRedeem));
-            if (spend > 0) {
-                await pointsRepository.redeem({
-                    userId: uid,
-                    points: spend,
-                    orderId: orderIds[0],
-                    description: `Redeemed on ${orderIds[0]}`,
-                });
-            }
-        }
-        catch (err) {
-            /*
-             * A failed redemption must not fail a placed order. The buyer keeps the
-             * points and paid full price — the strictly safer side of this trade.
-             */
-            const normalized = normalizeError(err);
-            serverLogger.error("points redemption failed after order creation", {
-                uid,
-                orderId: orderIds[0],
-                message: normalized.message,
-            });
-        }
-    }
     dispatchOrderConfirmationEmails(emailsToSend);
     serverLogger.info(`createCheckoutOrderAction: ${orderIds.length} order(s) placed for uid=${uid}` +
         (unavailable.length > 0 ? ` (${unavailable.length} item(s) unavailable)` : ""));
@@ -1315,7 +1559,14 @@ export async function previewCheckoutPricing(input) {
     for (const { items: group } of orderGroups) {
         const firstItem = group[0].item;
         const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
-        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId);
+        /*
+         * D44: `groupTotal` is already computed one line above with `lineTotalFor`
+         * and was simply not being passed — so the PREVIEW told the buyer they owed
+         * shipping on an order that qualified for the store's free-above threshold,
+         * and then the order path (equally unpassed) charged it. Preview and charge
+         * agreed, and both were wrong in the same direction.
+         */
+        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
         // Add-ons are per store, read off the cart document — the same entry
         // createOrderForGroup will read when the order is actually placed.
         const addons = cart.storeAddons?.[firstItem.storeId] ?? {};
@@ -1382,6 +1633,17 @@ export async function previewCheckoutPricing(input) {
             shippingFee: (s, sel) => computeShipmentProtectionFee(s, sel, commissions),
             saleFee: (s, sel) => computeSaleProtectionFee(s, sel, commissions),
         });
+        /*
+         * G1 — the discount is computed BEFORE the GST block below, the same hoist
+         * `createOrderForGroup` now has. It sat AFTER it until 2026-10-21, so the
+         * tax figure SHOWN to the buyer was backed out of the undiscounted gross.
+         *
+         * The preview and the charge must agree on the taxable BASE, not only on
+         * the total (Root Cause #59) — so the ordering has to match in both, which
+         * makes the position of this block load-bearing rather than incidental.
+         */
+        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
+        const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
         let groupGstAmount = 0;
         if (siteSettings?.gst?.enabled && resolvedAddress?.state) {
             /*
@@ -1395,10 +1657,23 @@ export async function previewCheckoutPricing(input) {
             // Same helper createOrderForGroup uses — the two disagreeing is the
             // recurring defect here (Root Cause #59), and it is the buyer seeing one
             // tax figure and being charged another.
-            groupGstAmount = sumGroupGst(group.map(({ item }) => item), resolvedProductById, intra ?? false).gstAmount;
+            groupGstAmount = sumGroupGst(group.map(({ item }) => item), resolvedProductById, intra ?? false, groupCouponDiscount, 
+            /*
+             * G5 — the same five ancillary charges the order path taxes, in the
+             * same order, so the figure SHOWN and the figure CHARGED cannot
+             * diverge on the tax base (Root Cause #59). All five are already in
+             * scope here, so unlike `createOrderForGroup` no block had to move.
+             *
+             * `groupEmiSurcharge` is deliberately absent — a financing charge with
+             * its own treatment, outside the decided scope — and the platform fee
+             * is absent because it already carries `platformFeeGst`.
+             */
+            roundRupees(groupShippingFee +
+                groupCodHandlingFee +
+                groupGiftWrapFee +
+                groupShipmentProtectionFee +
+                groupSaleProtectionFee)).gstAmount;
         }
-        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
-        const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
         stores.push({
             storeId: firstItem.storeId,
             storeName: firstItem.storeName || firstItem.storeId,
@@ -1569,6 +1844,18 @@ async function refundDroppedItemsForPhonePeCheckout(input) {
              */
             reasonCode: "not_received",
             reasonNote: `Automatic refund — ${unavailablePaid.length} item(s) unavailable at checkout: ${unavailablePaid.map((u) => u.productTitle).join(", ")}`,
+            /*
+             * A NATURAL key, not a uuid — and this is a money fix in its own right,
+             * not just satisfying a new required field.
+             *
+             * This path runs inside the gateway-settlement flow, which is itself
+             * retried: by the browser's `/verify`, by the webhook, and now (Phase 0)
+             * by the gateway's own 5xx retry. Every one of those retries used to
+             * mint a fresh `randomUUID()` and issue ANOTHER real refund for the same
+             * dropped items. Keying on the gateway order id makes the whole
+             * auto-refund idempotent across every retry of the checkout.
+             */
+            idempotencyKey: `oos_${phonepeOrderId}`,
             method: "phonepe",
             phonepeOrderId,
             confirmIrrevocable: true,
@@ -1644,7 +1931,9 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     // Reuses the same store/seller lookup as the COD/UPI path above instead
     // of re-implementing it inline — was two sequential findById calls per
     // seller group here, duplicated from resolveShippingCost.
-    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections } = await resolveShippingCost(firstItem.storeId);
+    // D44: `groupTotal` is computed just above — pass it so a free-above
+    // threshold can fire and an unpriceable store is recorded.
+    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
     /*
      * Same supplier-of-record rule as `createOrderForGroup`, through the same
      * function. This path (PhonePe verify / webhook) is the SECOND place an
@@ -1743,14 +2032,28 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         if (intra === null) {
             serverLogger.warn("[gst] place of supply undetermined on the online path — defaulting to inter-state (IGST)", { storeId: firstItem.storeId, hasStoreState: !!storeState });
         }
-        const summary = sumGroupGst(group.map(({ item }) => item), phonepeProductById, intra ?? false);
+        // G1 — post-discount taxable base. `couponDiscount` is already computed
+        // ~100 lines above in this function, so unlike the other two call sites no
+        // hoist was needed here; only the argument was missing.
+        const summary = sumGroupGst(group.map(({ item }) => item), phonepeProductById, intra ?? false, couponDiscount, 
+        /*
+         * G5 — the ancillary charges. 🛑 FOUR, not five: this is the ONLINE
+         * payment path, so there is no `codHandlingFee` in scope and none is
+         * charged — COD is a different payment method handled by
+         * `createOrderForGroup`. The absence is correct, not an omission, and
+         * worth saying so because the other two call sites pass five and a
+         * reader comparing them would otherwise look for the missing term.
+         */
+        roundRupees(shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee));
         if (summary.taxableAmount > 0 || summary.exemptAmount > 0)
             phonepeGst = summary;
     }
     /* Product GST is not a term — prices are tax-inclusive, so it is already
      * inside `groupTotal`. Matches the COD/UPI path exactly; `platformFeeGst`
      * stays because that is GST on our fee, charged on top. */
-    const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst;
+    // D42: rounded once on the sum — see the COD/UPI path's 🛑 for why a raw
+    // float sum of seven 2dp terms reached Firestore as 1011.8000000000001.
+    const orderTotal = roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst);
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     // Same expansion as the COD/UPI path. This was a THIRD hand-rolled copy of
     // the price rule (`isBundle ? item.price : product.price`) that — like the
@@ -1833,6 +2136,10 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         shippingAddress,
         notes,
         platformFee,
+        // Persisted alongside the fee — see the COD/UPI path's note. Both paths
+        // charged this to the buyer and recorded only the combined `gstAmount`,
+        // leaving the refund path to re-derive it from live percentages (D32).
+        platformFeeGst: platformFeeGst > 0 ? platformFeeGst : undefined,
         shippingFee: shippingFee > 0 ? shippingFee : undefined,
         giftWrapAddon: giftWrapFee > 0 ? true : undefined,
         giftWrapFee: giftWrapFee > 0 ? giftWrapFee : undefined,
@@ -1942,15 +2249,39 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             throw new ValidationError(ERROR_MESSAGES.CHECKOUT.PAYMENT_FAILED);
         }
     }
-    // Idempotency: the buyer's /verify call and the async webhook can both
-    // race to confirm+place for the same PhonePe payment (see the module
-    // comment above). `.create()` throws on conflict, so whichever caller
-    // creates this claim doc first is the sole placer; the loser returns
-    // whatever the winner already placed, or a retryable "in progress" error
-    // if the winner genuinely hasn't finished yet.
+    /*
+     * Idempotency: the buyer's /verify call and the async webhook can both race
+     * to confirm+place for the same payment (see the module comment above).
+     * `.create()` throws on conflict, so whichever caller creates this claim doc
+     * first is the sole placer; the loser returns whatever the winner already
+     * placed.
+     *
+     * 🛑 THE CLAIM CARRIES A LEASE, AND THAT IS NOT A REFINEMENT — IT IS THE
+     * WHOLE POINT. Measured in production 2026-10-21: `order_TqJvzY4gVjR2cc` /
+     * `pay_TqJx88j8OB7dSJ`, ₹2,511.80 captured by UPI, no order, and a manual
+     * refund from the Razorpay dashboard.
+     *
+     * The old version wrote `{ claimedAt }` and nothing else. Everything below
+     * this block — ~400 lines, a dozen throw sites, `ADDRESS_REQUIRED` and the
+     * amount guard among them — runs AFTER the claim is taken, and **nothing
+     * released it on failure**. So one failed placement made the claim a
+     * tombstone: every later attempt hit ALREADY_EXISTS, found zero orders, and
+     * returned "still being confirmed — please refresh". Refreshing could never
+     * work. The error told the buyer to do the one thing guaranteed to fail.
+     *
+     * A lease fixes it without a 400-line try/catch, and fixes strictly more: a
+     * `catch` cannot run if the process is killed mid-placement, and an expired
+     * lease is reclaimable either way. The loser now distinguishes three states
+     * rather than two — placed, genuinely in flight, or abandoned.
+     */
     const claimRef = getAdminDb().collection("gatewayOrderClaims").doc(merchantOrderId);
+    const claimNow = new Date();
+    const claimLease = {
+        claimedAt: claimNow,
+        leaseExpiresAt: new Date(claimNow.getTime() + GATEWAY_CLAIM_LEASE_MS),
+    };
     try {
-        await claimRef.create({ claimedAt: new Date() });
+        await claimRef.create(claimLease);
     }
     catch (claimErr) {
         void normalizeError(claimErr);
@@ -1962,7 +2293,45 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
                 itemCount: existingOrders.length,
             };
         }
-        throw new ValidationError(ERROR_MESSAGES.CHECKOUT.ORDER_PLACEMENT_IN_PROGRESS);
+        /*
+         * No order, and the holder's lease has run out: the previous attempt died
+         * or threw. Take the claim over rather than refusing forever.
+         *
+         * The takeover is a TRANSACTION, not a bare update, because two retries
+         * can arrive together — and two placers for one payment is the duplicate
+         * order this claim exists to prevent. Re-reading inside the transaction
+         * means exactly one of them wins the takeover; the other sees a fresh
+         * lease and backs off.
+         */
+        const tookOver = await getAdminDb()
+            .runTransaction(async (tx) => {
+            const snap = await tx.get(claimRef);
+            const held = snap.data();
+            const expiresAt = held?.leaseExpiresAt?.toDate?.();
+            // A claim written before this field existed has no lease — treat it as
+            // expired rather than immortal, which is the bug being fixed. Every
+            // tombstone already in the collection is reclaimed by this line.
+            if (expiresAt && expiresAt.getTime() > Date.now())
+                return false;
+            tx.update(claimRef, {
+                claimedAt: new Date(),
+                leaseExpiresAt: new Date(Date.now() + GATEWAY_CLAIM_LEASE_MS),
+                // Incremented in JS rather than with `FieldValue.increment`: the
+                // read is already inside this transaction, so it serialises
+                // correctly — and `firebase-admin/firestore` is loaded lazily here
+                // to keep it out of client graphs (Root Cause #24).
+                takeoverCount: (held?.takeoverCount ?? 0) + 1,
+            });
+            return true;
+        })
+            .catch((txErr) => {
+            void normalizeError(txErr);
+            return false;
+        });
+        if (!tookOver) {
+            throw new ValidationError(ERROR_MESSAGES.CHECKOUT.ORDER_PLACEMENT_IN_PROGRESS);
+        }
+        serverLogger.warn("gateway claim taken over from an expired lease", { merchantOrderId });
     }
     /*
      * THE authoritative check, for either gateway: re-fetch the order from the
@@ -2024,15 +2393,36 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
     if (!cart.items || cart.items.length === 0) {
         throw new ValidationError(ERROR_MESSAGES.CHECKOUT.CART_EMPTY);
     }
-    // Same lane priority + locked-line revalidation the manual/COD path runs.
-    //
-    // 🛑 This path carries no selectedItemIds, so it settles the ACTIVE LANE —
-    // not the cart. It used to pass `cart.items` as its own "selected" set,
-    // which made assertCheckoutLane compare the whole cart against its own
-    // active lane and throw on every multi-lane cart. Everything downstream
-    // reads `settleItems` for the same reason: stock decrements, jurisdiction
-    // and the order rows must cover exactly what was charged for.
-    const settleItems = defaultCheckoutItems(cart.items);
+    /*
+     * Same lane priority + locked-line revalidation the manual/COD path runs.
+     *
+     * 🛑 D40 — THIS LINE USED TO IGNORE THE BUYER'S SELECTION, and the capture
+     * route did not. `defaultCheckoutItems(cart.items)` is the active lane and
+     * nothing else, while `/api/payment/create-order` filtered by
+     * `cart.selectedItemIds` and fell back to the WHOLE CART across every lane.
+     * Two divergences fell out of that:
+     *
+     *   with a selection → charged for the selected items, orders for the whole
+     *                      lane: goods and stock leaving without payment.
+     *   no selection     → charged for EVERY lane, orders for one: the buyer
+     *                      OVERPAYS, and multi-lane carts are the normal product
+     *                      of the lane model (see `defaultCheckoutItems`).
+     *
+     * `resolveCheckoutItems` is now the one definition both paths call: active
+     * lane first, then the selection as a filter within it. Everything
+     * downstream still reads `settleItems`, because stock decrements,
+     * jurisdiction checks and the order rows must cover exactly what was charged.
+     */
+    const settleItems = resolveCheckoutItems(cart.items, cart.selectedItemIds);
+    if (settleItems.length === 0) {
+        /*
+         * An empty intersection is a refusal, not a fallback. It means the
+         * selection names only off-lane items — so the buyer is looking at
+         * something the server will not sell them, and widening to the whole lane
+         * would charge them for lines they deliberately unticked.
+         */
+        throw new ValidationError(ERROR_MESSAGES.CHECKOUT.CART_EMPTY);
+    }
     assertCheckoutLane(cart.items, settleItems);
     await assertLockedLinesStillValid(settleItems, uid);
     const isDigitalCartPp = cartIsDigitalOnly(settleItems);
@@ -2125,13 +2515,25 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         throw new ValidationError(ERROR_MESSAGES.CHECKOUT.INSUFFICIENT_STOCK);
     }
     {
-        // SB-UNI-5 2026-05-13 — bundle cart-lines use item.price (locked
-        // bundlePrice) instead of the representative member's product.price.
-        const cartSubtotalRs = productChecks.reduce((sum, { item, product }) => {
-            const isBundle = Boolean(item.bundleCategorySlug && item.bundleProductIds?.length);
-            const unit = isBundle ? item.price : product.price;
-            return sum + unit * item.quantity;
-        }, 0);
+        /*
+         * 🛑 D38 — this guard used to HAND-ROLL the price rule it is guarding:
+         *
+         *     const isBundle = Boolean(item.bundleCategorySlug && item.bundleProductIds?.length);
+         *     const unit = isBundle ? item.price : product!.price;
+         *
+         * It reproduced the BUNDLE branch of `unitPriceFor` and omitted the
+         * `lockedPrice` and `groupMembers` ones — which is precisely what that
+         * function's docstring forbids, and the fifth copy of the rule found
+         * across three sessions (Root Cause #75).
+         *
+         * The failure was the worst available shape. On an accepted ₹800 offer for
+         * a ₹1,000 listing: the capture route takes ₹800 (it uses `lineTotalFor`),
+         * this guard expects ₹1,000, `paid < expected − 1` fires, and the function
+         * THROWS — after the money has already been taken, on a branch with no
+         * refund. The buyer is charged and gets no order. That is the D64 incident
+         * class, reached by a different door.
+         */
+        const cartSubtotalRs = productChecks.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
         // Must use the SAME helper /api/payment/create-order used to compute what
         // it charged. This block used to re-derive the fee inline from the raw
         // percentages, so the moment the cap landed it would have expected more
@@ -2143,7 +2545,45 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         // below will use to build each order's recorded totalPrice) — keeps this
         // floor check from passing an amount that's short by the shipping fee.
         const expectedShippingGroups = splitCartIntoOrderGroups(bucketedPaid.available);
-        const expectedShippingFees = await Promise.all(expectedShippingGroups.map((g) => resolveShippingCost(g.items[0].item.storeId)));
+        /*
+         * The coupon, which this guard also omitted — the mirror of D37, and the
+         * two MUST move together. With the capture route now correctly deducting
+         * the discount, a guard that does not would expect MORE than was collected
+         * and would reject every legitimate coupon payment — turning an overcharge
+         * into a post-capture throw, which is strictly worse.
+         *
+         * Grouped identically to the capture route (`splitCartIntoOrderGroups` over
+         * the same available items), so the two compute the same number from the
+         * same shape rather than agreeing by coincidence.
+         */
+        const { couponDiscount: expectedCouponDiscount } = computeCartCouponDiscount(cart.appliedCoupons ?? [], expectedShippingGroups.map((g) => ({
+            storeId: g.items[0].item.storeId,
+            lines: g.items.map(({ item, product }) => ({
+                itemId: item.itemId,
+                lineTotal: lineTotalFor(item, product),
+            })),
+        })));
+        const expectedDiscountedSubtotal = Math.max(0, cartSubtotalRs - expectedCouponDiscount);
+        const expectedShippingFees = await Promise.all(
+        /*
+         * 🛑 D44 — THE GUARD MUST PASS `goodsValue` TOO, AND IN THIS SAME
+         * COMMIT. This is the D37/D38 sequencing trap, one defect over.
+         *
+         * The capture route and both order paths now quote with the group's real
+         * goods value, so a store's free-above threshold can fire and shipping
+         * can legitimately be ₹0. A guard still quoting with `goodsValue: 0`
+         * would compute the UN-thresholded fee, expect more than was collected,
+         * trip `paid < expected − 1`, and **throw after the money was taken** —
+         * converting a fixed overcharge into a charged-with-no-order, which is
+         * the D64 incident class and strictly worse than the bug being fixed.
+         *
+         * Verified by construction rather than by hope: the goods value here is
+         * computed with `lineTotalFor` over the same `expectedShippingGroups`
+         * the capture route groups, so the two cannot disagree about the base.
+         */
+        expectedShippingGroups.map((g) => resolveShippingCost(g.items[0].item.storeId, {
+            goodsValue: g.items.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
+        })));
         const expectedShippingFee = expectedShippingFees.reduce((sum, r) => sum + r.shippingFee, 0);
         // Add-ons are per store, so the expected total sums each group's own
         // selection — a single cart-wide figure would over- or under-count as soon
@@ -2185,11 +2625,44 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
          * would make this guard demand ~₹580 more than the buyer owes on a
          * ₹5,547 cart — rejecting every correctly-charged order.
          */
-        const expectedPaymentAmountRs = cartSubtotalRs + expectedPlatformFee + expectedGstOnFee + expectedAddonFees + expectedShippingFee;
+        const expectedPaymentAmountRs = expectedDiscountedSubtotal +
+            expectedPlatformFee +
+            expectedGstOnFee +
+            expectedAddonFees +
+            expectedShippingFee;
         // Reuses the order already fetched above to confirm COMPLETED — PhonePe's
         // own amount is in its wire-format smallest unit. // audit-money-units-ok: describes the PhonePe boundary conversion this line performs, not our storage convention
         const paidAmountRs = paiseToRupees(gatewayOrder.amount);
-        if (paidAmountRs < expectedPaymentAmountRs - 1) {
+        /*
+         * ── TWO-SIDED, and the second side is how D37 survived ─────────────────
+         *
+         * 🛑 This read `paidAmountRs < expectedPaymentAmountRs - 1` — a FLOOR
+         * check only. An over-capture of any size passed silently, which is
+         * exactly what let the missing coupon term go unnoticed: the gateway took
+         * the undiscounted amount, this guard saw "paid ≥ expected" and waved it
+         * through, and the order recorded the discounted figure. Nothing in our
+         * data disagreed.
+         *
+         * A ceiling is now checked too. The tolerance stays asymmetric and that is
+         * deliberate rather than sloppy:
+         *
+         *   UNDER by > ₹1   → we were short-changed. Refuse.
+         *   OVER  by > ₹1   → the BUYER was over-charged. Record loudly, and
+         *                     PROCEED to place the order.
+         *
+         * Proceeding on an over-capture is the important choice. The alternative —
+         * throwing — is what D38 did, and it leaves the buyer charged with no
+         * order and no refund on that branch, which is the D64 incident class.
+         * Placing the order means the buyer has what they paid for and the surplus
+         * is a recorded, refundable discrepancy rather than a vanished payment.
+         * Phase 4's reconciler reads `amount_mismatch` rows and opens a case; the
+         * refund itself waits for Phase 1's idempotency key, because an automatic
+         * refund on top of a non-idempotent refund path is a double-refund
+         * generator.
+         */
+        const amountDelta = paidAmountRs - expectedPaymentAmountRs;
+        const AMOUNT_TOLERANCE_RS = 1;
+        if (amountDelta < -AMOUNT_TOLERANCE_RS) {
             serverLogger.warn(`Payment amount mismatch for user ${uid}: paid ₹${paidAmountRs}, expected ≥ ₹${expectedPaymentAmountRs}`);
             failedCheckoutRepository
                 .logPayment(uid, "amount_mismatch", `Paid ₹${paidAmountRs}, expected ≥ ₹${expectedPaymentAmountRs}`, {
@@ -2201,6 +2674,18 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
                 .catch((err) => { void normalizeError(err); serverLogger.warn(AUDIT_LOG_FAIL_MSG, { error: err instanceof Error ? err.message : String(err) }); });
             throw new ValidationError(ERROR_MESSAGES.CHECKOUT.PAYMENT_FAILED);
         }
+        if (amountDelta > AMOUNT_TOLERANCE_RS) {
+            serverLogger.error(`OVER-CAPTURE for user ${uid}: paid ₹${paidAmountRs}, expected ₹${expectedPaymentAmountRs} (surplus ₹${amountDelta.toFixed(2)}) — order will still be placed`, { merchantOrderId, expectedCouponDiscount });
+            failedCheckoutRepository
+                .logPayment(uid, "amount_mismatch", `OVER-CAPTURE: paid ₹${paidAmountRs}, expected ₹${expectedPaymentAmountRs}, surplus ₹${amountDelta.toFixed(2)} — refund owed`, {
+                gatewayOrderId: gatewayOrder.gatewayOrderId,
+                gatewayPaymentId: merchantOrderId,
+                amountRs: paidAmountRs,
+                addressId,
+            })
+                .catch((err) => { void normalizeError(err); serverLogger.warn(AUDIT_LOG_FAIL_MSG, { error: err instanceof Error ? err.message : String(err) }); });
+            // Deliberately NO throw — see above.
+        }
     }
     const { coupons: appliedCoupons, dropped: droppedCoupons } = await revalidateAppliedCoupons(cart.appliedCoupons ?? [], bucketedPaid.available, uid);
     // "skip_items" (or an all-available cart under any policy) — build order