@mohasinac/appkit 4.71.0 → 4.72.0

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

@@ -12,8 +12,21 @@ import { roundRupees } from "../../../../utils/number.formatter.js";
 import { ApiError, ValidationError, NotFoundError, ERROR_MESSAGES } from "../../../../errors/index.js";
 import { ORDER_FIELDS } from "../../../../constants/field-names.js";
 import { serverLogger } from "../../../../monitoring/index.js";
-import { roundShippingUp, } from "../../../shared/shipping/quote.js";
-import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories/index.js";
+/*
+ * 🛑 `roundShippingUp` is NO LONGER IMPORTED HERE, and its absence is the fix.
+ * It was applied to a client-supplied `chargedRate` and the result was charged
+ * — see `CreateCheckoutOrderInput.selectedShippingQuote`. The ₹50 step now
+ * applies only where a carrier rate ENTERS the system (`toQuoteOptions`) and
+ * inside `buildShippingOptions`, never to anything a browser sent.
+ */
+import { toQuoteOptions, } from "../../../shared/shipping/quote.js";
+import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, sellerProfileRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, 
+/*
+ * Phase 3 — the split-settlement records written by the capture request, read
+ * back here so each order can record whether ITS seller's share went straight
+ * to them out of escrow. That record is the double-payment guard.
+ */
+payoutRepository, } from "../../../../repositories/index.js";
 import { isIntraStateSupply } from "../../../shared/fees/calculator.js";
 import { resolveStateKey, INDIA_STATES } from "../../../shared/fees/india-states.js";
 import { allocatePointsAcrossGroups, pointsBaseForGroup, computePreOrderDepositAmount, lineTotalFor, resolvePointsTender, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
@@ -34,6 +47,15 @@ import { failedCheckoutRepository } from "../../../../features/checkout/reposito
 import { sendOrderConfirmationEmail } from "../../../../features/contact/server.js";
 import { splitCartIntoOrderGroups } from "../../../../features/orders/utils/order-splitter.js";
 import { DEFAULT_STORE_SHIPPING_POLICY, quoteShipping, toStoreShippingPolicy, } from "../../../shared/features/shipping/mode.js";
+/*
+ * The seller's offer, the buyer's pick, and the SERVER's price for it — the
+ * money-authority fix of 2026-11-08. `offer.ts`'s header carries the measured
+ * defect (a forged `chargedRate` of 1 moved a ₹149 order's total from ₹172.69
+ * to ₹222.69) and the reason the fix is re-resolution rather than prohibition:
+ * the buyer legitimately CHOOSES between the seller's own rate and a carrier
+ * quote, so what must be rejected is the client's AMOUNT, never its CHOICE.
+ */
+import { CUSTOM_SHIPPING_OPTION_ID, DEFAULT_SELLER_SHIPPING_OFFER, buildShippingOptions, impliedObligation, offerFromPolicy, platformShippingOptionId, resolveShippingSelection, toSellerShippingOffer, } from "../../../shared/features/shipping/offer.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 —
@@ -57,7 +79,6 @@ import { CART_COLLECTION } from "../../../../features/cart/schemas/index.js";
 // S-SBUNI-RULES 2026-05-13 — bundle cart-line stock fan-out helpers.
 import { getCartItemMemberIds, getExpandedDecrements, bucketCartItemsByStock, isMultiMemberLine, } from "./bundle-expansion.js";
 import { expandCartLineToOrderRows } from "./expand-order-items.js";
-import { freezePartsOnItems } from "./freeze-parts.js";
 import { OrderStatusValues, PaymentStatusValues, PaymentMethodValues, OutOfStockPolicyValues, } from "../../../../features/orders/schemas/index.js";
 import { getDefaultCurrency } from "../../../../core/baseline-resolver.js";
 import { getProviders } from "../../../../contracts/index.js";
@@ -74,18 +95,55 @@ import { amountDueNow, emiOrderFields, groupEmiGate, groupEmiQuote, groupEmiSche
 import { formatShippingAddress } from "./data.js";
 import { enforceMaxPerUserForCart } from "./prize-bundle-gates.js";
 import { getListingRule, runSyncPreflight, assertPaymentMethodAllowed, assertEmiOptInAllowed, } from "../../../shared/checkout/rules/index.js";
+/*
+ * Phase 1c — the PER-CART gateway choice. `assertCollectingGateway` refuses
+ * before capture (the `"online"` tender in `createCheckoutOrderAction`);
+ * `resolveCollectingGatewayForCart` is the non-throwing form, used at SETTLE
+ * where the money has already moved and a refusal would only deny the buyer
+ * the order they paid for. See `gateway-selection.ts`.
+ */
+import { assertCollectingGateway, resolveCollectingGatewayForCart, } from "./gateway-selection.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 { cartIsDigitalOnly, cartRequiresShipping } from "../../../shared/listing-types/cart-shipping.js";
 import { processRefundAction } from "../refunds/actions.js";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
 import { resolveDisplayedUpiId } from "./upi-resolution.js";
 import { resolveSupplierIdentity } from "./supplier-identity.js";
 import { PAYMENT_WINDOW_MS } from "../../../../features/orders/constants/payment-window.js";
 import { assertCheckoutValueOtp } from "./value-otp-gate.js";
+/*
+ * Item 1.39 — the blocking buyer policy agreement. Lives under
+ * `_internal/server/payments/` rather than beside the other checkout gates
+ * because BOTH order paths need it and one of them (the gateway path) takes
+ * consent in a different request from the one that places the order.
+ */
+import { assertBuyerPolicyConsent, attachOrdersToPolicyConsent, loadBuyerPolicyConsent, } from "../../payments/policy-consent.js";
+/*
+ * The fulfilment question, asked of the ORDER WORKFLOW REGISTRY rather than of
+ * a listing-type literal. See the call site in `finalizeOrderPlacement`: both
+ * predicates fold the capability row together with the listing's own
+ * `digitalCode.codeDeliveryMethod` opt-in, which is the half the old
+ * `listingType === "digital-code"` comparison could not see.
+ */
+import { awaitsManualRelease, fulfilsOnPayment, } from "../../../shared/features/orders/workflow-registry.js";
+/*
+ * The `pending_release` write. Server-side and transactional, so it lives
+ * beside the release action it hands the line over to rather than in the shared
+ * registry — the registry decides, this performs.
+ */
+import { markAwaitingRelease } from "../digital-code/release.js";
+/*
+ * 🛑 The ONLY legal way to read `finalSale`. The field is optional and the
+ * platform default is TRUE, so `!p.finalSale` and `p.finalSale === true` both
+ * misread absence — see the helper's own header. Imported from the defining
+ * module rather than a barrel: it is a pure predicate with no firebase-admin
+ * in its chain.
+ */
+import { isFinalSale } from "../../../../features/products/constants/final-sale.js";
 const AUDIT_LOG_FAIL_MSG = "checkout: audit log failed (non-critical)";
 /**
  * How long a `gatewayOrderClaims` holder owns the right to place an order
@@ -278,6 +336,9 @@ opts) {
             storeEmiEnabled: false,
             storeState: undefined,
             shippingPolicy: DEFAULT_STORE_SHIPPING_POLICY,
+            // No store, so no offer. The default is custom at ₹0 — the same thing
+            // `DEFAULT_STORE_SHIPPING_POLICY` says, and for the same reason.
+            shippingOffer: { ...DEFAULT_SELLER_SHIPPING_OFFER },
             shippingUnavailable: false,
             storeProtections: { shipping: false, sale: false },
             // No store, so no seller to absorb a redemption.
@@ -287,6 +348,9 @@ opts) {
             // No store, so no seller registration — the caller falls back to the
             // platform's via resolveSupplierIdentity.
             storeTaxIdentity: undefined,
+            // No store, so no vendor. The split builder treats that as NOT settleable
+            // and refuses the capture rather than collecting into our own account.
+            settlementVendors: undefined,
         };
     }
     const store = await storeRepository.findById(storeId);
@@ -398,6 +462,21 @@ opts) {
         storeEmiEnabled,
         storeState,
         shippingPolicy: policy,
+        /*
+         * 🛑 Resolved from the STORED `shippingPricing` document, falling back to
+         * the offer the legacy single mode implies — never from anything the
+         * client sent. `toSellerShippingOffer` reads the explicit `offer` when the
+         * seller has saved one and derives it from `mode` otherwise, so there is
+         * one stored field and one reader rather than a second config system
+         * (`mode.ts`'s header records what happened last time there were two).
+         *
+         * `store?.shippingPricing` is passed rather than `policy`, because the
+         * explicit offer is a sibling of `mode` on that document and `policy` has
+         * already discarded it.
+         */
+        shippingOffer: store?.shippingPricing
+            ? toSellerShippingOffer(store.shippingPricing)
+            : offerFromPolicy(policy),
         shippingUnavailable: quote.kind === "unavailable",
         storeProtections: {
             shipping: store?.supportsShippingProtection === true,
@@ -429,8 +508,106 @@ opts) {
                 registeredAddress: store.registeredAddress,
             }
             : undefined,
+        /*
+         * Raw and per gateway — see the field's own 🛑. The store document is
+         * already in hand, so this costs nothing; deciding settleability here would
+         * mean guessing which gateway collects.
+         */
+        settlementVendors: store?.settlementVendors,
     };
 }
+/**
+ * The carrier options for a destination, obtained SERVER-SIDE at order time.
+ *
+ * ## 🛑 This outbound call is the whole point
+ *
+ * `CreateCheckoutOrderInput.selectedShippingQuote` used to carry the rates, and
+ * its own docstring conceded the gap: *"the gap worth closing is re-quoting the
+ * carrier at order time, which costs an outbound call on the payment path and
+ * is tracked separately."* It is closed here. One call, only for a seller who
+ * actually accepts carrier quotes, and only when the buyer picked one — a cart
+ * whose seller ships their own way performs no call at all.
+ *
+ * ## 🛑 Returns `[]` on EVERY failure, and `[]` means "no platform option"
+ *
+ * Not "free", and not "trust whatever the client said". An empty list makes
+ * `resolveShippingSelection` refuse a platform pick with
+ * `no-method-available`, which is the owner's own rule for this case: *"the
+ * platform option is ABSENT at checkout rather than guessed."* The alternatives
+ * are both money defects — guessing a rate charges the buyer a number no
+ * carrier quoted, and falling back to the client's figure is the defect this
+ * whole change exists to remove.
+ *
+ * Today the registered provider is `ManualShippingProvider`, whose
+ * `checkServiceability` returns `{ isServiceable: true, couriers: [] }` — so
+ * this legitimately yields zero options on every call until a real carrier
+ * account is wired, and a forged platform pick is therefore REFUSED rather than
+ * mispriced. Measured, not assumed: `providers.config.ts` defaults
+ * `siteSettings.shipping.provider` to `"manual"`.
+ */
+async function carrierOptionsForDestination(pincode, weightKg) {
+    if (!pincode)
+        return [];
+    const shipping = getProviders().shipping;
+    if (!shipping) {
+        serverLogger.error("checkout carrier re-quote: no shipping provider registered", {
+            pincode,
+        });
+        return [];
+    }
+    try {
+        const result = await shipping.checkServiceability(pincode, weightKg);
+        if (!result.isServiceable)
+            return [];
+        return toQuoteOptions(result.couriers);
+    }
+    catch (err) {
+        /*
+         * A carrier outage must not 500 a checkout. It removes the platform option
+         * — which is a refusal the buyer can act on ("choose the seller's own
+         * shipping, or retry") — rather than taking the order at a price nobody
+         * quoted.
+         */
+        serverLogger.error("checkout carrier re-quote failed", {
+            pincode,
+            err: err instanceof Error ? err.message : String(err),
+        });
+        return [];
+    }
+}
+/**
+ * The carrier's own minimum weight slab, used when the cart cannot say what the
+ * parcel weighs.
+ *
+ * Same figure and same reasoning as `POST /api/shipping/quote`: the cart does
+ * not reliably carry per-item weights, 0.5 kg is the carrier's own floor, and a
+ * heavier parcel quotes low — which the reconciliation rule already handles by
+ * making the seller absorb the difference. Shared as a constant so the quote
+ * the buyer was shown and the quote the order is priced from cannot differ by
+ * their default weight.
+ */
+export const CHECKOUT_DEFAULT_PARCEL_WEIGHT_KG = 0.5;
+/**
+ * Which option id the buyer's posted pick corresponds to.
+ *
+ * 🛑 Reads the IDENTITY out of `selectedShippingQuote` and discards every
+ * amount on it. That object is a legacy wire shape carrying
+ * `rawRate`/`chargedRate`, and those two numbers are precisely what must not
+ * reach the total — so this function exists to make the narrowing mechanical
+ * rather than a thing each call site has to remember.
+ *
+ * A pick whose `courierId` is the literal custom id maps to the custom option;
+ * `platformShippingOptionId` namespaces carrier ids for exactly that reason, so
+ * a carrier returning `"custom"` cannot land a buyer on the wrong side of the
+ * fulfilment obligation.
+ */
+function requestedShippingOptionId(quote) {
+    if (!quote?.courierId)
+        return undefined;
+    if (quote.courierId === CUSTOM_SHIPPING_OPTION_ID)
+        return CUSTOM_SHIPPING_OPTION_ID;
+    return platformShippingOptionId(quote.courierId);
+}
 /**
  * The pre-C5b flat number, read as a `flat` mode.
  *
@@ -440,8 +617,9 @@ opts) {
 async function legacyFlatPolicy(storeOwnerId) {
     if (!storeOwnerId)
         return DEFAULT_STORE_SHIPPING_POLICY;
-    const sellerUser = await userRepository.findById(storeOwnerId);
-    const legacy = sellerUser?.shippingConfig;
+    // shippingConfig is seller-only data — sellerProfiles, not users.
+    const sellerProfile = await sellerProfileRepository.findById(storeOwnerId);
+    const legacy = sellerProfile ? sellerProfileRepository.revealProfile(sellerProfile).shippingConfig : undefined;
     if (!legacy?.isConfigured)
         return DEFAULT_STORE_SHIPPING_POLICY;
     const amount = legacy.customShippingPrice ?? 0;
@@ -729,15 +907,127 @@ async function settlePointsTender(input) {
         });
     }
 }
+/**
+ * §Payment cross-gateway duplication pass (overhaul brief, 2026-11-05) —
+ * the ~45-line post-write side-effect tail `createOrderForGroup` and
+ * `createPhonePeGroupOrder` both ran in the exact same order, independently
+ * copy-pasted: settlePointsTender → finalizeLockedLines → digital-code
+ * claim → coupon-usage accumulation → email queueing →
+ * emitOrderPlacedNotifications. Pure sequencing, no business-logic
+ * branching between the two copies — the plan's own read-first pass found
+ * this the one real, clean consolidation candidate (the order-literal
+ * assembly itself is NOT: real per-gateway field differences there trip
+ * the Duplication Decision Framework's keep-separate rule).
+ *
+ * `paymentMethod`/`paid` are the only two values that differ between the
+ * two original call sites (dynamic on the manual/COD path, a fixed
+ * `PaymentMethodValues.ONLINE`/`true` on the online-gateway path) — both
+ * are caller-supplied params here rather than re-derived, so this function
+ * makes no payment-method assumption of its own.
+ *
+ * `emailsToSend` is the SAME shared, whole-checkout accumulator array both
+ * original call sites pushed into directly (mutated by reference, same
+ * pattern `couponUsageAccumulator` already uses) — not a return value,
+ * since the caller flushes it once per whole checkout, not per group.
+ */
+async function finalizeOrderPlacement(input) {
+    const { orderId, uid, group, pointsApplied, pointsBudget, firstItem, userEmail, userName, groupCouponCodes, couponUsageAccumulator, emailsToSend, orderItems, totalQuantity, orderTotal, shippingAddress, paymentMethod, storeOwnerId, paid, storeId, } = input;
+    // The second half of the points tender — see `settlePointsTender`. Runs
+    // before the caller asks the gateway for anything.
+    await settlePointsTender({ orderId, userId: uid, pointsApplied, pointsBudget });
+    // Close the loop on any locked line this order settled: flip the offer to
+    // "paid" (its terminal status had NO server-side writer before 2026-08-21,
+    // so an accepted offer could be re-added and re-ordered) and back-link the
+    // winning bid to the order it became.
+    await finalizeLockedLines(group.map(({ item }) => item), orderId);
+    /*
+     * SB-UNI-N — fulfilment on payment, decided by CAPABILITY and by the
+     * seller's own opt-in. Fire-and-forget on the claim: the order is already
+     * persisted, so an exhausted pool is logged rather than thrown.
+     *
+     * 🛑 This used to read `listingType === "digital-code"`, which was wrong in a
+     * way a typecheck could never see. `digitalCode.codeDeliveryMethod` is
+     * seller-settable (`auto-claim` | `manual-email`), is in the seller form, is
+     * validated by the request schema, and two seeded listings already carry
+     * `manual-email` — but the type comparison auto-claimed a code regardless.
+     * A seller who deliberately chose to release codes by hand got instant issue
+     * anyway, and the setting looked implemented while doing nothing.
+     *
+     * `fulfilsOnPayment` / `awaitsManualRelease` answer the two questions this
+     * site actually has ("does this line complete on its own when the money
+     * lands?" / "is a human release owed?") out of
+     * `fulfilmentModeFor`, which reads the capability registry × the listing's
+     * opt-in. So enabling instant or deferred fulfilment on another listing type
+     * is a capability-row edit plus that type's flag — never an edit here.
+     *
+     * 🛑 `markAwaitingRelease` is AWAITED while the claim is not, and the
+     * asymmetry is deliberate: a claim that fails leaves the pool untouched and
+     * the line simply undelivered, whereas a `pending_release` that fails to
+     * write leaves a paid line indistinguishable from one whose pool was empty —
+     * the ambiguity that function exists to remove. One of those is a normal
+     * state the buyer should see; the other is an incident.
+     */
+    const fulfilmentProduct = group[0]?.product;
+    if (fulfilsOnPayment(fulfilmentProduct?.listingType, fulfilmentProduct)) {
+        claimDigitalCodeForOrder(getAdminDb(), firstItem.productId, orderId, uid, {
+            userEmail: userEmail || undefined,
+            userName,
+            productTitle: firstItem.productTitle,
+        }).catch((e) => serverLogger.error("claimDigitalCode", { error: normalizeError(e).message }));
+    }
+    else if (awaitsManualRelease(fulfilmentProduct?.listingType, fulfilmentProduct)) {
+        await markAwaitingRelease(orderId, firstItem.productId);
+    }
+    for (const code of groupCouponCodes) {
+        const entry = couponUsageAccumulator.get(code);
+        if (entry)
+            entry.orderIds.push(orderId);
+    }
+    if (userEmail) {
+        emailsToSend.push({
+            to: userEmail,
+            userName,
+            orderId,
+            productTitle: orderItems.length > 1 ? `${orderItems.length} items` : firstItem.productTitle,
+            quantity: totalQuantity,
+            totalPrice: orderTotal,
+            currency: firstItem.currency ?? getDefaultCurrency(),
+            shippingAddress,
+            paymentMethod,
+            items: orderItems,
+        });
+    }
+    emitOrderPlacedNotifications({
+        orderId,
+        buyerUid: uid,
+        buyerName: userName,
+        storeOwnerId,
+        productLabel: orderItems.length > 1 ? `${orderItems.length} items` : firstItem.productTitle,
+        paid,
+        storeId,
+    });
+}
 /**
  * Places one order for one seller-group of the checkout cart — fee math
  * (COD deposit/handling, EMI schedule), coupon apportionment, order-doc
  * creation, digital-code claim, and notification fan-out. Pushes into
- * `ctx.orderIds` / `ctx.emailsToSend` and returns the group's pre-fee total
- * so the caller can accumulate the checkout-wide `total`.
+ * `ctx.orderIds` / `ctx.emailsToSend` and returns the group's full,
+ * fee-inclusive charged total (`orderTotal`) so the caller can accumulate
+ * the checkout-wide `total` — 🛑 CORRECTED 2026-11-05: this used to return
+ * `groupTotal` (the pre-fee goods subtotal only), while the sibling
+ * `createPhonePeGroupOrder` returned `orderTotal` (the full amount) under
+ * the identically-typed, identically-named `CheckoutOrderResult.total`.
+ * Confirmed latent, not live-user-visible (the checkout success page reads
+ * the freshly-fetched Firestore order's own `totalPrice`, which was always
+ * `orderTotal`-correct on both paths) — but the in-memory return value is
+ * summed across every seller-group in `orderGroups.reduce`-style checkout
+ * orchestration, where only the full fee-inclusive figure is the correct
+ * term (shipping/GST/fees are computed per-group already, never shared
+ * across groups, so summing `orderTotal` per group cannot double-count
+ * anything here).
  */
 async function createOrderForGroup(group, orderType, ctx) {
-    const { paymentMethod, emiOptIn, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, deliverySnapshot, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, platformFeeByStore, selectedShippingQuote, useAllPoints, pointsBudget, } = ctx;
+    const { paymentMethod, emiOptIn, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, deliverySnapshot, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, policyConsent, platformFeeByStore, selectedShippingQuote, selectedShippingOptions, useAllPoints, pointsBudget, } = ctx;
     const firstItem = group[0].item;
     const firstProduct = group[0].product;
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
@@ -788,7 +1078,14 @@ async function createOrderForGroup(group, orderType, ctx) {
      * capped. It never throws — a parts list we could not read must not fail a
      * payment (see the module header).
      */
-    const orderItems = await freezePartsOnItems(baseOrderItems);
+    /*
+     * Part 14 (parts freezing) REMOVED 2026-11-08 — owner decision. The parts
+     * taxonomy (partGlossary · modelComposition) leaves the shop database
+     * entirely; the wiki owns it as JSON and will expose an API for it, the way
+     * it already does for tools. There is no composition to read here any more,
+     * so this is the pure expansion it always wanted to be.
+     */
+    const orderItems = baseOrderItems;
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
     /*
      * D44: the group's real goods value, so free-above-threshold can fire.
@@ -798,25 +1095,133 @@ async function createOrderForGroup(group, orderType, ctx) {
      * 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, acceptsPoints, sharedPurchaseRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupGoodsValue });
+    const { shippingFee: resolvedShippingFee, shippingOffer, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity, acceptsPoints, sharedPurchaseRates } = 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.
+     * ════════════════════════════════════════════════════════════════════════
+     * 🛑 SERVER AUTHORITY OVER THE SHIPPING FEE — owner's spec, 2026-11-08
+     * ════════════════════════════════════════════════════════════════════════
+     *
+     * ## What was here, and what it cost
+     *
+     *   shippingFee = roundShippingUp(selectedShippingQuote.chargedRate)
+     *
+     * `resolveShippingCost` was called, its answer destructured, and then
+     * DISCARDED whenever the client posted a quote. Measured live on a ₹149 item:
+     * an honest request charged **₹172.69**; a forged `{ chargedRate: 1 }`
+     * charged **₹222.69**. A client-supplied number reached the charged total.
      *
-     * `roundShippingUp` is idempotent, so re-applying it to an honest value is a
-     * no-op; applied to a tampered one it forces the result back onto a ₹50 step.
-     * That bounds what a forged `chargedRate` can be to "some carrier rate,
-     * correctly rounded" rather than an arbitrary number.
+     * The comment that stood here argued the trust was bounded because
+     * `roundShippingUp` re-rounds the value. It does — onto a ₹50 step. ₹1
+     * becomes ₹50 and ₹10,000 stays ₹10,000, so the "bound" was the attacker's
+     * choice of multiple of fifty, in either direction. Undercutting was
+     * unexploitable only because no seeded store had `shippingPricing` set, so
+     * every resolved fee was ₹0 — a data accident due to expire the moment a
+     * vendor saved a real rate.
      *
-     * Applied to the FIRST group only — see the field's note on OrderGroupContext.
-     * A cart spanning sellers must not be charged the same parcel rate twice.
+     * ## 🛑 Why the fix is NOT "reject any client shipping value"
+     *
+     * The owner's spec gives the buyer a real choice between the seller's own
+     * rate and a live carrier quote, *"if they find the other cheap they can
+     * choose whatever they wish"*. So the client MUST be able to say which option
+     * it picked. What it must never say is what that option costs.
+     *
+     * Hence: the posted object contributes its `courierId` ONLY
+     * (`requestedShippingOptionId` discards `rawRate` and `chargedRate`), the
+     * option is re-priced from the seller's STORED offer plus a carrier quote
+     * this server obtained itself, and an option the seller does not offer is a
+     * REFUSAL rather than a fallback — charging the buyer for a method they did
+     * not choose is the same wrong pointing the other way.
+     *
+     * ## 🛑 `shippingRequired` is a CAPABILITY read
+     *
+     * `cartRequiresShipping` asks the registry for `supportsShipping` on each
+     * line. A digital-code group therefore acquires no fee and no fulfilment
+     * obligation — not because this code knows what a digital code is, but
+     * because no line in it supports shipping. No `listingType ===` anywhere.
+     *
+     * ## 🛑 Still FIRST GROUP ONLY
+     *
+     * Unchanged from before and for the unchanged reason: the picker quotes one
+     * destination, and a cart split across sellers must not be charged the same
+     * parcel rate once per seller. See the field's note on `OrderGroupContext`.
      */
     const isFirstGroup = ctx.orderIds.length === 0;
-    const shippingFee = selectedShippingQuote && isFirstGroup
-        ? roundShippingUp(selectedShippingQuote.chargedRate)
-        : selectedShippingQuote
+    const groupRequiresShipping = cartRequiresShipping(group.map(({ product }) => ({ listingType: product.listingType })));
+    /*
+     * 🛑 THE PER-STORE PICK WINS, and the legacy cart-wide one is the fallback.
+     *
+     * `selectedShippingOptions[storeId]` is the shape the owner's spec needs —
+     * each seller offers their own methods, so each group has its own answer, and
+     * `mocks/18-shipping-fees.qm` shows two shipping lines in one order summary.
+     * The legacy `selectedShippingQuote` stays usable for a tab opened before
+     * that field existed, and stays FIRST-GROUP-ONLY for the reason it always
+     * was: it quoted one destination for the whole cart, so honouring it on every
+     * group would charge a multi-seller cart the same parcel rate N times.
+     */
+    const requestedOptionId = selectedShippingOptions?.[firstItem.storeId] ??
+        (isFirstGroup ? requestedShippingOptionId(selectedShippingQuote) : undefined);
+    /*
+     * The outbound call is skipped unless it can change the answer: the seller
+     * must accept carrier quotes AND the buyer must have picked one. An ordinary
+     * checkout against a self-shipping seller performs no carrier call at all,
+     * which is what keeps this inside Rule #6's round-trip budget.
+     */
+    const needsCarrierQuote = groupRequiresShipping &&
+        shippingOffer.platformQuotesAccepted &&
+        requestedOptionId !== undefined &&
+        requestedOptionId !== CUSTOM_SHIPPING_OPTION_ID;
+    const carrierOptions = needsCarrierQuote
+        ? await carrierOptionsForDestination(deliverySnapshot?.deliveryPincode, CHECKOUT_DEFAULT_PARCEL_WEIGHT_KG)
+        : [];
+    const selection = resolveShippingSelection({
+        shippingRequired: groupRequiresShipping,
+        offer: shippingOffer,
+        goodsValue: groupGoodsValue,
+        carrierOptions,
+        requestedOptionId,
+    });
+    /*
+     * 🛑 REFUSES rather than falling back, and the refusal happens BEFORE any
+     * money moves on this path (`createCheckoutOrderAction` is the COD/manual
+     * entry point; the gateway path runs the same resolution inside
+     * `verifyAndPlaceGatewayOrderAction`). `groupEmiGate` directly below sets the
+     * precedent and states the reason: *"silently producing a full-price order
+     * from an EMI request is money the buyer did not agree to."* Silently
+     * producing a differently-shipped order from a shipping request is the same
+     * class of wrong.
+     */
+    if (selection.kind === "refused") {
+        throw new ValidationError(selection.message);
+    }
+    const shippingFee = selection.kind === "resolved"
+        ? selection.option.amount
+        : selection.kind === "not-required"
             ? 0
-            : resolvedShippingFee;
+            : /*
+               * `unselected` — this seller got no pick, so their stored single-mode
+               * policy answers, exactly as it did before the picker existed. Still
+               * a SERVER number: `resolveShippingCost` computed it from
+               * `shippingPricing`, and nothing the client sent is in it.
+               *
+               * 🛑 The one case that charges ₹0 instead: a LATER group under the
+               * LEGACY cart-wide quote, with no per-store pick anywhere. That quote
+               * priced one parcel to one destination, so billing it again here
+               * would charge the buyer twice for one courier — the behaviour this
+               * branch has always had, preserved deliberately rather than
+               * inherited. A per-store pick never reaches it.
+               */
+                isFirstGroup || !selectedShippingQuote || selectedShippingOptions
+                    ? resolvedShippingFee
+                    : 0;
+    /**
+     * What the buyer committed to, frozen so part C of the spec is evidenced.
+     *
+     * 🛑 Written only on the group that actually CARRIES the fee. A later group
+     * in a multi-seller cart is charged ₹0 shipping, and recording a
+     * self-fulfilment obligation there would bind a seller to a price they were
+     * never paid.
+     */
+    const shippingObligation = selection.kind === "resolved" ? selection.obligation : undefined;
     /*
      * Who issues this invoice — the seller if they have their own GSTIN, the
      * platform otherwise. ONE function decides, and it is the only place that
@@ -1216,7 +1621,7 @@ async function createOrderForGroup(group, orderType, ctx) {
         orderType,
         // How the buyer earned the right to buy at this price. `orderType` cannot
         // answer that — it has five values, and both a settled win and a buyout
-        // are "auction". Written ONCE here and never recomputed: the auction and
+        // are "collector-drop". Written ONCE here and never recomputed: the collector drop and
         // offer documents it summarises are mutable and eventually archived.
         sourceContext,
         /*
@@ -1225,13 +1630,46 @@ async function createOrderForGroup(group, orderType, ctx) {
          * carries the shipping fee — a later group in a multi-seller cart is
          * charged ₹0 shipping, so recording a quote there would invite a credit
          * against money that group never collected.
+         *
+         * 🛑 REBUILT FROM THE SERVER'S RESOLUTION, not from the posted object.
+         * `rawRate` is the carrier's own figure as WE re-quoted it; it used to be
+         * whatever the client sent, which meant `reconcileShipping` later compared
+         * a seller's real spend against a buyer-supplied number. Only a platform
+         * option has a carrier rate at all — the seller's own price is not a
+         * carrier quote and must not masquerade as one, so a custom pick records
+         * the obligation below and no `selectedShippingQuote`.
          */
-        selectedShippingQuote: selectedShippingQuote && isFirstGroup
-            ? { ...selectedShippingQuote, chargedRate: shippingFee }
+        selectedShippingQuote: selection.kind === "resolved" && selection.option.kind === "platform"
+            ? {
+                courierId: selection.option.courierId ?? selection.option.optionId,
+                courierName: selection.option.courierName ?? selection.option.label,
+                rawRate: carrierOptions.find((c) => c.courierId === selection.option.courierId)?.rawRate ??
+                    selection.option.amount,
+                chargedRate: shippingFee,
+                estimatedDays: selection.option.estimatedDays ?? 0,
+                // Stamped server-side. A buyer-supplied timestamp is unverifiable,
+                // and this field exists so a stale quote is recognisable later.
+                quotedAt: new Date(),
+            }
             : undefined,
+        /*
+         * ── PART C: THE FULFILMENT OBLIGATION, RECORDED ───────────────────────
+         *
+         * Owner: *"if they have selected that, then it is up to the seller to
+         * fulfil as is, they cannot use the platform to ship for the other, as we
+         * have already taken money from the customer."*
+         *
+         * 🛑 Written at checkout because the rule is BROKEN at pack time, possibly
+         * days later. A rule nobody can evidence after the fact is not a rule —
+         * `mayBookPlatformLabel` reads this one field, and `reconcileShipping`
+         * already computes both money directions (excess back to the buyer,
+         * shortfall absorbed by the seller) from `chargedAmount` versus the real
+         * spend. This flag is what says which of them the seller agreed to.
+         */
+        shippingObligation,
         offerId: firstItem.offerId ?? undefined,
-        // Distinguishes a Buy Now purchase from a settled auction win. Both are
-        // orderType "auction"; only this one gets the 24h admin-review window.
+        // Distinguishes a Buy Now purchase from a settled collector drop win. Both are
+        // orderType "collector-drop"; only this one gets the 24h admin-review window.
         isBuyout: firstItem.isBuyout ? true : undefined,
         status: adminBypass ? OrderStatusValues.PROCESSING : OrderStatusValues.PENDING,
         paymentStatus: adminBypass ? PaymentStatusValues.PAID : PaymentStatusValues.PENDING,
@@ -1363,55 +1801,41 @@ async function createOrderForGroup(group, orderType, ctx) {
         imageUrls: imageUrls.length > 0 ? imageUrls : undefined,
         outOfStockPolicy,
         droppedItems: droppedItems.length > 0 ? droppedItems : undefined,
+        /*
+         * Item 1.39 — the consent record, stamped on EVERY order this checkout
+         * produced rather than on the first one.
+         *
+         * 🛑 A multi-seller cart splits into N orders and each is separately
+         * cancellable, refundable and disputable, so each needs the agreement that
+         * governs it. Writing it once and joining through a batch id would make
+         * "what did this buyer agree to for this order" a query that can fail.
+         */
+        policyConsent,
         ...extraOrderFields,
     });
     orderIds.push(order.id);
-    // The second half of the points tender — see `settlePointsTender`. Runs
-    // before the caller asks the gateway for anything.
-    await settlePointsTender({ orderId: order.id, userId: uid, pointsApplied, pointsBudget });
-    // Close the loop on any locked line this order settled: flip the offer to
-    // "paid" (its terminal status had NO server-side writer before 2026-08-21,
-    // so an accepted offer could be re-added and re-ordered) and back-link the
-    // winning bid to the order it became.
-    await finalizeLockedLines(group.map(({ item }) => item), order.id);
-    // SB-UNI-N — claim a digital code for digital-code orders (fire-and-forget,
-    // order is already persisted so a claim failure is logged, not thrown).
-    if ((group[0]?.product?.listingType ?? "standard") === "digital-code") {
-        claimDigitalCodeForOrder(getAdminDb(), firstItem.productId, order.id, uid, {
-            userEmail: userEmail || undefined,
-            userName,
-            productTitle: firstItem.productTitle,
-        }).catch((e) => serverLogger.error("claimDigitalCode", { error: normalizeError(e).message }));
-    }
-    for (const code of groupCouponCodes) {
-        const entry = couponUsageAccumulator.get(code);
-        if (entry)
-            entry.orderIds.push(order.id);
-    }
-    if (userEmail) {
-        emailsToSend.push({
-            to: userEmail,
-            userName,
-            orderId: order.id,
-            productTitle: orderItems.length > 1 ? `${orderItems.length} items` : firstItem.productTitle,
-            quantity: totalQuantity,
-            totalPrice: orderTotal,
-            currency: firstItem.currency ?? getDefaultCurrency(),
-            shippingAddress,
-            paymentMethod,
-            items: orderItems,
-        });
-    }
-    emitOrderPlacedNotifications({
+    await finalizeOrderPlacement({
         orderId: order.id,
-        buyerUid: uid,
-        buyerName: userName,
+        uid,
+        group,
+        pointsApplied,
+        pointsBudget,
+        firstItem,
+        userEmail,
+        userName,
+        groupCouponCodes,
+        couponUsageAccumulator,
+        emailsToSend,
+        orderItems,
+        totalQuantity,
+        orderTotal,
+        shippingAddress,
+        paymentMethod,
         storeOwnerId,
-        productLabel: orderItems.length > 1 ? `${orderItems.length} items` : firstItem.productTitle,
         paid: adminBypass,
         storeId: order.storeId,
     });
-    return groupTotal;
+    return orderTotal;
 }
 /**
  * Place order(s) from the user's cart in a single Firestore transaction.
@@ -1585,6 +2009,52 @@ export async function createCheckoutOrderAction(input) {
             preTxProductById.set(preTxLookup.productIds[i], snap.data());
         }
     }
+    /*
+     * ── ITEM 1.39 — THE BLOCKING BUYER POLICY AGREEMENT ───────────────
+     *
+     * Pre-mutation and pre-capture. Everything between the cart read and here is
+     * reads and validation; the transaction is far below. This is the last point
+     * at which refusing costs nothing. On the COD/manual path "before the order"
+     * and "before the money" are the same instant; on the gateway path they are
+     * two different requests, which is why that path takes its consent at
+     * create-order time instead (see `verifyAndPlaceGatewayOrderAction`).
+     *
+     * 🛑 Throws on absence or mismatch. A consentless order is REJECTED, never
+     * placed-with-a-warning — the no-refund-after-reveal mechanic is only
+     * defensible if the agreement that enables it was actually taken.
+     *
+     * 🛑 LISTING TYPES COME FROM THE PRODUCT DOCUMENTS — not the cart's
+     * denormalised copy, and never the request. `CartItemDocument.listingType` is
+     * written server-side at add-to-cart time, which makes it untampered but not
+     * CURRENT: a product retyped to a concealed listing after it was added would
+     * leave a stale `standard` on the line, and the reveal clause would be
+     * silently dropped from the one order that most needs it.
+     * `preTxProductById` is the authoritative read and is already in hand for the
+     * max-per-user gate, so this costs no extra round trip — which is why the
+     * gate sits here rather than beside the OTP check above.
+     *
+     * The cart copy is the FALLBACK for a line whose product could not be read
+     * (deleted mid-checkout — the stock check below refuses it anyway), and
+     * `standard` is the last resort: it carries `supportsShipping`, so the
+     * no-refund-after-dispatch clause still applies rather than vanishing.
+     */
+    const policyConsent = await assertBuyerPolicyConsent({
+        uid,
+        listingTypes: cartItems.map((item) => (preTxProductById.get(item.productId)?.listingType ??
+            item.listingType ??
+            "standard")),
+        settings: siteSettings?.checkoutPolicies,
+        submitted: input.policyConsent,
+        capturedOn: "checkout",
+        /*
+         * 🛑 A REQUEST, re-verified inside the gate against
+         * `admin:checkout:bypass` — never a trusted boolean. `adminBypass` arrives
+         * on this action's own input, so the day a route wires it from a request
+         * body a trusted flag here would make the whole consent gate switchable off
+         * by any client. The gate answers 403 when the uid does not hold it.
+         */
+        requestAdminBypass: adminBypass,
+    });
     /*
      * Payment-method gate — before `enforceMaxPerUserForCart`, which runs count
      * queries, because this answer needs no reads at all.
@@ -1595,18 +2065,93 @@ export async function createCheckoutOrderAction(input) {
      * every member of every line against this map.
      *
      * 🛑 This ONE call site is complete coverage, and that is worth stating so
-     * nobody adds a second. Only `cod`/`cash`/`emi` are ever blocked (auction,
+     * nobody adds a second. Only `cod`/`cash`/`emi` are ever blocked (collector drop,
      * bundle, prize-draw) and all three arrive here; the Razorpay path is always
      * `"online"`, which no rule blocks — and a throw there would land AFTER
      * capture, taking the buyer's money and then refusing the order. Pre-capture
      * is the only safe place for this, and the method is decided here.
      */
-    assertPaymentMethodAllowed(cartItems, preTxProductById, paymentMethod);
+    /*
+     * 🛑 The third argument is NOT optional in effect, even though its type
+     * allows omission. The gate FAILS CLOSED: a listing type carrying
+     * `requiresGatewayPermission` (collector-drop, clearance) is refused
+     * online payment unless the ACTIVE gateway declares it accepts that type.
+     * Razorpay and PhonePe declare nothing, because both name "Bidding/Auction
+     * houses" in their prohibited-merchant lists; only Cashfree opens them.
+     *
+     * Read off the registered provider rather than compared against the string
+     * "cashfree", so a second permitted gateway is a change to that adapter and
+     * not to this call site (Root Cause #61).
+     */
+    /*
+     * ── Phase 1c: WHICH gateway may collect, for the ONLINE tender ────────────
+     *
+     * 🛑 Gated on `paymentMethod === "online"`, and that gate is the rule rather
+     * than an optimisation. The commingling this guards against is a property of
+     * a GATEWAY CAPTURE: the money lands in the aggregator's escrow and is
+     * settled out of it. COD, cash and a manual bank/UPI transfer involve no
+     * capture at all — a manual transfer is already buyer-to-whoever-the-admin-
+     * names — so applying the rule there would refuse the one set of tenders
+     * that has no commingling problem.
+     *
+     * 🛑 Reachable, which is why this is not capture-route-only: `/api/checkout`
+     * accepts `paymentMethod: "online"`, so this action creates orders for an
+     * online tender BEFORE any capture exists. Guarding only
+     * `/api/payment/create-order` would leave this entry point open.
+     *
+     * 🛑 RESOLVED NON-THROWING FIRST, so the gate below can be told which gateway
+     * would really collect. Passing `getProviders().payment` there — the
+     * process-level tie-break winner — would refuse a collector-drop whenever
+     * PhonePe sorts ahead of an enabled Cashfree, i.e. exactly the configuration
+     * Phase 1c exists to make work. The two gates then compose instead of
+     * disagreeing.
+     */
+    const collectingGateway = paymentMethod === "online"
+        ? resolveCollectingGatewayForCart({
+            items: cartItems,
+            productById: preTxProductById,
+            platformStoreId: siteSettings?.payment?.platformStoreId,
+        })
+        : null;
+    assertPaymentMethodAllowed(cartItems, preTxProductById, paymentMethod, {
+        /*
+         * The gateway that would actually collect when there is one; otherwise the
+         * process default, which is what every non-online tender is measured
+         * against and is unchanged. Either way `undefined` means ACCEPTS NOTHING
+         * (`PaymentGateContext.gatewayAccepts`), so a failed resolution cannot
+         * widen this.
+         */
+        gatewayAccepts: collectingGateway
+            ? collectingGateway.provider?.acceptsRestrictedListingTypes
+            : getProviders().payment?.acceptsRestrictedListingTypes,
+    });
+    /*
+     * Thrown AFTER the listing-level gate, deliberately. A listing that forbids
+     * online payment outright (`blockedPaymentMethods`) should say so in its own
+     * words; the gateway refusal is the narrower, second reason and must not
+     * mask it. When only this one binds it throws `GATEWAY_UNAVAILABLE_FOR_CART`
+     * naming which of the two independent constraints applied.
+     */
+    if (collectingGateway && !collectingGateway.resolution.ok) {
+        /*
+         * Re-resolves rather than re-throwing the stored resolution, because the
+         * error SHAPE (code, `constraint`, `detail`) belongs to
+         * `assertCollectingGateway` and must have exactly one definition — a
+         * hand-rolled `Object.assign(new ValidationError(...))` here would be a
+         * second one to drift from (Root Cause #61). The resolution is pure with
+         * no IO, so the repeat costs nothing.
+         */
+        assertCollectingGateway({
+            items: cartItems,
+            productById: preTxProductById,
+            platformStoreId: siteSettings?.payment?.platformStoreId,
+        });
+    }
     /*
      * 🛑 The second axis needs its own assertion, and omitting it would have
      * been a silent regression of a rule that already exists.
      *
-     * `prizeDrawRule.blockedPaymentMethods` lists `"emi"` because winner
+     * `clearanceRule.blockedPaymentMethods` lists `"emi"` because winner
      * assignment waits on confirmed payment. Once EMI stopped being a tender,
      * that entry stopped matching anything — the gate above would see
      * `upi_manual` (explicitly ALLOWED for prize draws) and wave through an
@@ -1757,12 +2302,28 @@ export async function createCheckoutOrderAction(input) {
     const emailsToSend = [];
     const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
-    // One commission on one transaction, capped, then apportioned across the
-    // orders this cart splits into — see allocateCheckoutFees.
+    /*
+     * The buyer-facing platform fee: a TAPERED per-unit rate, summed per cart
+     * line, then GST. See `DEFAULT_PLATFORM_FEE_UNIT_BANDS` for the owner's three
+     * rulings and for the delta against `mocks/18-shipping-fees.qm`, which still
+     * draws a flat ₹10 per LINE.
+     */
+    /*
+     * 🛑 `item.quantity` PER LINE, as an array — never a flattened total and
+     * never `expandCartLineToOrderRows`'s output.
+     *
+     * Per line because the taper bands per line: 8 units as two lines of 4 bills
+     * at ₹10 each (₹80); as one line of 8 it bills at ₹8 (₹64). Never the
+     * expansion because a BX-53 deck set is ONE listing purchased — ₹10, not ₹60
+     * — however many components the box holds (owner, 2026-11-08).
+     */
+    const lineUnitsOf = (g) => g.map(({ item }) => item.quantity ?? 0);
+    const lineUnitsByStore = new Map(orderGroups.map(({ items: g }) => [g[0].item.storeId, lineUnitsOf(g)]));
+    const cartLineUnits = orderGroups.flatMap(({ items: g }) => lineUnitsOf(g));
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
         g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
-    ]), computeCheckoutFees(cartSubtotal, commissions));
+    ]), computeCheckoutFees(cartSubtotal, commissions, cartLineUnits), lineUnitsByStore, commissions);
     /*
      * ── The checkout's points budget, read ONCE (D46/D47) ─────────────────────
      *
@@ -1807,8 +2368,10 @@ export async function createCheckoutOrderAction(input) {
         gstSettings: siteSettings?.gst,
         siteContactUpiVpa: siteSettings?.contact?.upiVpa,
         storeAddons: cart.storeAddons,
+        policyConsent,
         platformFeeByStore,
         selectedShippingQuote: input.selectedShippingQuote,
+        selectedShippingOptions: input.selectedShippingOptions,
         productById: checkoutProductById,
         useAllPoints,
         pointsBudget,
@@ -1816,6 +2379,13 @@ export async function createCheckoutOrderAction(input) {
     for (const { items: group, orderType } of orderGroups) {
         total += await createOrderForGroup(group, orderType, groupCtx);
     }
+    /*
+     * Item 1.39 — backlink the consent to the orders it covered. Never awaited
+     * for correctness: the authoritative copy is already on each order document,
+     * so this is the convenience index and a failure must not undo a successful
+     * placement. See `attachOrdersToPolicyConsent`, which swallows and logs.
+     */
+    await attachOrdersToPolicyConsent(policyConsent.consentId, orderIds);
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);
     /*
      * ── 🛑 THE POINTS REDEMPTION BLOCK WAS DELETED HERE, 2026-10-21 (D46) ─────
@@ -1900,6 +2470,8 @@ const EMPTY_PRICING_PREVIEW = {
     couponDiscount: 0,
     platformFee: 0,
     gstOnFee: 0,
+    platformFeeUnitCount: 0,
+    platformFeeLines: [],
     sharedPurchaseFee: 0,
     total: 0,
     pointsApplied: 0,
@@ -1996,7 +2568,36 @@ export async function previewCheckoutPricing(input) {
          * 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, acceptsPoints, sharedPurchaseRates: previewSharedRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+        const { shippingFee: groupShippingFee, shippingOffer: groupShippingOffer, storeState, storeProtections, storeEmiEnabled, acceptsPoints, sharedPurchaseRates: previewSharedRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+        /*
+         * ── WHAT THE BUYER MAY CHOOSE, priced by the server ──────────────────
+         *
+         * Built from the seller's STORED offer plus a carrier quote this server
+         * obtained, so the picker offers exactly what `resolveShippingSelection`
+         * will accept at order time. See the field's note on
+         * `CheckoutPricingPreviewStore` for why offering anything else means the
+         * buyer meets a refusal after pressing pay.
+         *
+         * 🛑 `cartRequiresShipping` is a CAPABILITY read (`supportsShipping` off
+         * the registry). A digital-code group offers nothing and is charged
+         * nothing — no listing-type comparison anywhere in the decision.
+         *
+         * 🛑 The carrier call is skipped unless the seller accepts carrier quotes.
+         * The preview runs on every control the buyer touches, so an unconditional
+         * outbound call here would be a rate-limited third-party request per
+         * keystroke. A self-shipping seller's options are pure arithmetic.
+         */
+        const groupRequiresShipping = cartRequiresShipping(group.map(({ product }) => ({ listingType: product?.listingType })));
+        const previewCarrierOptions = groupRequiresShipping && groupShippingOffer.platformQuotesAccepted
+            ? await carrierOptionsForDestination(resolvedAddress?.postalCode, CHECKOUT_DEFAULT_PARCEL_WEIGHT_KG)
+            : [];
+        const groupShippingOptions = groupRequiresShipping
+            ? buildShippingOptions({
+                offer: groupShippingOffer,
+                goodsValue: groupTotal,
+                carrierOptions: previewCarrierOptions,
+            })
+            : [];
         // 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] ?? {};
@@ -2047,8 +2648,18 @@ export async function previewCheckoutPricing(input) {
          * to have snapshotted it. The snapshot matters at the other two moments —
          * order creation (so the written row is authoritative) and claim time (so a
          * seller cannot flip the switch after the sale).
+         *
+         * 🛑 THROUGH `isFinalSale`, never `product?.finalSale === true`. The field
+         * is optional and the platform default is TRUE, so the bare comparison
+         * reads "not final sale" for every listing that has never set it — which
+         * is 53 of 53 products in the live catalogue (measured 2026-11-08). That
+         * made this preview offer SALE protection on lines that the order row
+         * written seconds later marks `finalSale: true`, and which
+         * `requestReturnAction`/`processRefundAction` then refuse: a fee quoted and
+         * charged for cover whose claim is guaranteed to be declined.
+         * `final-sale.ts` names this exact spelling as wrong in its header.
          */
-        const groupHasFinalSale = group.some(({ product }) => product?.finalSale === true);
+        const groupHasFinalSale = group.some(({ product }) => isFinalSale(product));
         /*
          * ── S5a in the PREVIEW ───────────────────────────────────────────────────
          *
@@ -2167,6 +2778,13 @@ export async function previewCheckoutPricing(input) {
             hasFinalSaleItem: groupHasFinalSale,
             acceptsPoints,
             sharedPurchaseFee: groupSharedPurchaseFee,
+            /*
+             * What the buyer may pick, priced server-side. Carried per STORE because
+             * shipping is charged per store and the cart splits on `storeId` — a
+             * cart-wide option list would offer one seller's custom rate for another
+             * seller's parcel.
+             */
+            shippingOptions: groupShippingOptions,
             // Filled by the tender pass below — it needs each store's share of the
             // one capped commission, which is only allocatable once every group is
             // known.
@@ -2187,15 +2805,23 @@ export async function previewCheckoutPricing(input) {
     const sharedPurchaseFeeTotal = sum((s) => s.sharedPurchaseFee);
     const gstAmount = sum((s) => s.gstAmount);
     const couponDiscount = sum((s) => s.couponDiscount);
-    // One capped commission for the whole checkout, on every payment method —
-    // deliberately not per store, so it is not added to the per-store rows above.
-    // The whole object is kept (not just the two fields) because the points
-    // tender below re-allocates it per store through `allocateCheckoutFees`,
-    // which takes a `CheckoutFees` — and `totalFee` carries the
-    // `minimumTransactionFee` floor, which is exactly the field D41 found had no
-    // consumer anywhere. Destructuring it away here would be how it loses its
-    // second one.
-    const checkoutFees = computeCheckoutFees(cartSubtotal, commissions);
+    // One fee for the whole checkout, on every payment method — deliberately not
+    // per store, so it is not added to the per-store rows above. The whole object
+    // is kept (not just the two fields) because the points tender below
+    // re-allocates it per store through `allocateCheckoutFees`, which takes a
+    // `CheckoutFees` — and `totalFee` carries the `minimumTransactionFee` floor,
+    // which is exactly the field D41 found had no consumer anywhere.
+    // Destructuring it away here would be how it loses its second one.
+    //
+    // 🛑 `cartLineUnits` is built from the SAME `orderGroups` the per-store
+    // rows above were built from, so the fee the buyer is SHOWN and the fee the
+    // order path CHARGES are derived from one line set rather than two that
+    // happen to agree — and under a per-line taper the SHAPE of that set changes
+    // the answer, not just its sum.
+    const previewLineUnitsOf = (g) => g.map(({ item }) => item.quantity ?? 0);
+    const previewLineUnitsByStore = new Map(orderGroups.map(({ items: g }) => [g[0].item.storeId, previewLineUnitsOf(g)]));
+    const cartLineUnits = orderGroups.flatMap(({ items: g }) => previewLineUnitsOf(g));
+    const checkoutFees = computeCheckoutFees(cartSubtotal, commissions, cartLineUnits);
     const { platformFee, gstOnFee } = checkoutFees;
     /*
      * 🛑 `gstAmount` is NOT a term, and leaving it in was a shown-vs-charged
@@ -2258,7 +2884,7 @@ export async function previewCheckoutPricing(input) {
     const previewUseAllPoints = cart.useAllPoints === true;
     const previewBalance = previewUseAllPoints ? await safePointsBalance(uid) : 0;
     if (previewUseAllPoints && previewBalance > 0) {
-        const feeByStore = allocateCheckoutFees(stores.map((s) => [s.storeId, s.subtotal]), checkoutFees);
+        const feeByStore = allocateCheckoutFees(stores.map((s) => [s.storeId, s.subtotal]), checkoutFees, previewLineUnitsByStore, commissions);
         const { perGroup } = allocatePointsAcrossGroups(stores.map((s) => {
             const share = feeByStore.get(s.storeId);
             return {
@@ -2291,6 +2917,8 @@ export async function previewCheckoutPricing(input) {
         couponDiscount,
         platformFee,
         gstOnFee,
+        platformFeeUnitCount: checkoutFees.unitCount,
+        platformFeeLines: checkoutFees.lines,
         total,
         pointsApplied,
         // Equal to `total` when no points apply, so every existing reader of
@@ -2452,7 +3080,7 @@ async function refundDroppedItemsForPhonePeCheckout(input) {
  * from the inline version this replaced.
  */
 async function createPhonePeGroupOrder(group, orderType, ctx) {
-    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, merchantOrderId, phonepeOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, buyerState, useAllPoints, pointsBudget, 
+    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, policyConsent, siteSettings, uid, userName, userEmail, merchantOrderId, gatewayOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, buyerState, useAllPoints, pointsBudget, 
     /*
      * 🛑 All three were DECLARED on the params above and never destructured,
      * so the body referenced them as free names: `emiOptIn`/`emiTenureMonths`
@@ -2461,7 +3089,7 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
      * why appkit's own `tsc` is the gate for this file and not a reading of
      * the diff.
      */
-    emiOptIn, emiTenureMonths, deliverySnapshot, } = ctx;
+    emiOptIn, emiTenureMonths, deliverySnapshot, splitByStore, } = ctx;
     /*
      * Which online gateway actually took the money, read off the registered
      * provider rather than passed in — exactly one is registered per process
@@ -2471,13 +3099,43 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
      */
     const gatewayName = getProviders().payment?.name ?? "phonepe";
     const firstItem = group[0].item;
+    /*
+     * What this seller was instructed to be settled out of this capture, if
+     * anything. Resolved once here rather than three times in the order literal
+     * below — a repeated `Map.get(...)!` is three chances for one of them to read
+     * a different key.
+     */
+    const splitForThisStore = splitByStore?.get(firstItem.storeId);
     const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
     // 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.
     // 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, acceptsPoints, sharedPurchaseRates, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+    const { shippingFee, shippingOffer, storeOwnerId, storeState, storeTaxIdentity, storeProtections, acceptsPoints, sharedPurchaseRates, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+    /*
+     * ── PART C ON THE ONLINE PATH, as far as it can honestly go ──────────────
+     *
+     * ⚠ GAP, STATED RATHER THAN PAPERED OVER: this path does NOT yet honour
+     * the buyer's per-store shipping option. It prices shipping from the seller's
+     * stored policy, and so does the capture route
+     * (`POST /api/payment/create-order`) and the post-capture guard — all three
+     * agree, so there is no client-trust hole here and never was; what is missing
+     * is the buyer CHOICE half of the owner's spec. Wiring it means changing the
+     * capture, the guard and this writer in one commit, because a guard expecting
+     * a differently-priced shipping term throws on an order already paid for.
+     *
+     * What CAN be recorded honestly is the obligation a seller's offer implies
+     * when it leaves no choice: a seller who offers only their own shipping is
+     * self-fulfilling whatever the buyer did or did not pick.
+     * `impliedObligation` answers `null` the moment there is a real choice, so
+     * nothing here invents a contract. Without it every online order would carry
+     * no obligation at all, and `mayBookPlatformLabel` fails OPEN on absence —
+     * i.e. the one gate part C depends on would be inert for the entire online
+     * path.
+     */
+    const gatewayGroupRequiresShipping = cartRequiresShipping(group.map(({ product }) => ({ listingType: product?.listingType })));
+    const gatewayShippingObligation = impliedObligation(shippingOffer, shippingFee, gatewayGroupRequiresShipping) ?? undefined;
     /*
      * The instalment schedule for THIS seller group, through the same helper the
      * COD/manual writer uses — not a copy of its block. Two hand-written
@@ -2548,8 +3206,15 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
      * and the one live store has `supportsSaleProtection` unset — but both of
      * those are a settings toggle away, and an under-charge that appears the
      * moment a flag flips is worse than one that is visible now.
+     *
+     * 🛑 `isFinalSale(product)`, not `product?.finalSale === true` — see the
+     * matching note in the preview above. `finalSale` is optional with a default
+     * of TRUE, so the bare comparison opted every one of the 53 catalogue
+     * listings OUT of final sale and let sale protection be billed on a line the
+     * written order row marks `finalSale: true`. This is the CHARGED path, so
+     * here it was money taken for a claim the refund gate will decline.
      */
-    const groupHasFinalSale = group.some(({ product }) => product?.finalSale === true);
+    const groupHasFinalSale = group.some(({ product }) => isFinalSale(product));
     const { shippingProtectionFee: shipmentProtectionFee, saleProtectionFee } = computeProtectionFees({
         subtotal: groupTotal,
         selected: {
@@ -2685,7 +3350,8 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
      * other: an accepted offer paid through PhonePe was recorded at the
      * seller's list price.
      */
-    const orderItems = await freezePartsOnItems(basePhonepeItems);
+    // Part 14 removed — see the note at the other call site.
+    const orderItems = basePhonepeItems;
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
     const imageUrls = [
         ...new Set(group
@@ -2728,12 +3394,12 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         orderType,
         // How the buyer earned the right to buy at this price. `orderType` cannot
         // answer that — it has five values, and both a settled win and a buyout
-        // are "auction". Written ONCE here and never recomputed: the auction and
+        // are "collector-drop". Written ONCE here and never recomputed: the collector drop and
         // offer documents it summarises are mutable and eventually archived.
         sourceContext,
         offerId: firstItem.offerId ?? undefined,
-        // Distinguishes a Buy Now purchase from a settled auction win. Both are
-        // orderType "auction"; only this one gets the 24h admin-review window.
+        // Distinguishes a Buy Now purchase from a settled collector drop win. Both are
+        // orderType "collector-drop"; only this one gets the 24h admin-review window.
         isBuyout: firstItem.isBuyout ? true : undefined,
         status: OrderStatusValues.CONFIRMED,
         paymentStatus: PaymentStatusValues.PAID,
@@ -2750,7 +3416,22 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
          */
         paymentId: merchantOrderId,
         paymentRecord: {
-            method: gatewayName === "razorpay" ? "razorpay" : "phonepe",
+            /*
+             * 🛑 Was a 2-way ternary (`razorpay` / else `phonepe`) with no `cashfree`
+             * branch — exactly the bug a 2-value check always risks once a third
+             * provider registers. Every Cashfree-settled order recorded
+             * `method: "phonepe"` and no `cashfreeOrderId`, which is wrong audit
+             * trail for a real, live gateway (Cashfree is the one this project
+             * uses specifically for collector-drop/clearance compliance — see
+             * CLAUDE.md § payment-cashfree). `gatewayName` is read off the
+             * REGISTERED provider three lines above this function's own top, so
+             * this is never a value the caller could get wrong.
+             */
+            method: gatewayName === "razorpay"
+                ? "razorpay"
+                : gatewayName === "cashfree"
+                    ? "cashfree"
+                    : "phonepe",
             transactionId: transactionId ?? merchantOrderId,
             /*
              * 🛑 What the gateway actually CAPTURED, which is `amountDue` once points
@@ -2768,10 +3449,43 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
                 merchantOrderId,
                 ...(gatewayName === "razorpay"
                     ? { razorpayOrderId: merchantOrderId, razorpayPaymentId: transactionId }
-                    : { phonepeOrderId }),
+                    : gatewayName === "cashfree"
+                        ? { cashfreeOrderId: gatewayOrderId }
+                        : { phonepeOrderId: gatewayOrderId }),
                 transactionId,
             },
         },
+        /*
+         * ── Split settlement: this seller's share never entered our account ─────
+         *
+         * 🛑 **THE DOUBLE-PAYMENT GUARD'S ONLY WRITER.** `orderNeedsManualPayout`
+         * reads it, and both mark-shipped writers consult that before setting
+         * `payoutStatus: "eligible"`. Without this field the weekly and automatic
+         * sweeps would create a `payouts` row for the FULL share of an order the
+         * aggregator has already settled — the seller paid twice, once out of
+         * escrow and once out of the platform's own balance.
+         *
+         * 🛑 Only written when the capture CARRIED an instruction for this store.
+         * It is never inferred from the gateway's name or from the store being
+         * third-party: if the split field had been silently ignored by the gateway
+         * (the one assumption in `payment-cashfree` whose failure mode is silent),
+         * an inferred flag would mark the order settled and the seller would never
+         * be paid at all. A missing entry here means the ordinary payout path,
+         * which is the safe direction — a seller chasing a late payout is
+         * recoverable; one who was never paid and whose order says otherwise is
+         * not.
+         */
+        splitSettlement: splitForThisStore
+            ? {
+                gateway: splitForThisStore.gateway || gatewayName,
+                vendorId: splitForThisStore.vendorId,
+                vendorAmount: splitForThisStore.amount,
+                // 🛑 The payout row's own `requestedAt`, never `new Date()` here —
+                // the settle request can be minutes after the capture.
+                instructedAt: splitForThisStore.instructedAt,
+                merchantOrderId,
+            }
+            : undefined,
         shippingAddress,
         notes,
         platformFee,
@@ -2780,6 +3494,12 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         // leaving the refund path to re-derive it from live percentages (D32).
         platformFeeGst: platformFeeGst > 0 ? platformFeeGst : undefined,
         shippingFee: shippingFee > 0 ? shippingFee : undefined,
+        /*
+         * The obligation this seller's offer IMPLIES, when it implies one. See the
+         * block above `gatewayShippingObligation` for the gap this partially covers
+         * and why it is partial rather than invented.
+         */
+        shippingObligation: gatewayShippingObligation,
         whatsappNotifyAddon: whatsappNotifyFee > 0 ? true : undefined,
         whatsappNotifyFee: whatsappNotifyFee > 0 ? whatsappNotifyFee : undefined,
         giftWrapAddon: giftWrapFee > 0 ? true : undefined,
@@ -2833,51 +3553,34 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         imageUrls: imageUrls.length > 0 ? imageUrls : undefined,
         outOfStockPolicy,
         droppedItems: unavailablePaid.length > 0 ? unavailablePaid : undefined,
+        /*
+         * Item 1.39 — the consent taken at CREATE-ORDER time, before the capture.
+         * Loaded back by id from the gateway's own passthrough channel rather than
+         * re-taken here: there is no buyer in the room on the webhook path, and
+         * asking for consent after the money moved would be meaningless anyway.
+         */
+        policyConsent,
         ...extraOrderFields,
     });
     orderIds.push(order.id);
-    // The second half of the points tender — one implementation, shared with the
-    // COD/manual path. See `settlePointsTender`.
-    await settlePointsTender({ orderId: order.id, userId: uid, pointsApplied, pointsBudget });
-    // Close the loop on any locked line this order settled: flip the offer to
-    // "paid" (its terminal status had NO server-side writer before 2026-08-21,
-    // so an accepted offer could be re-added and re-ordered) and back-link the
-    // winning bid to the order it became.
-    await finalizeLockedLines(group.map(({ item }) => item), order.id);
-    // SB-UNI-N — claim a digital code for digital-code orders (fire-and-forget,
-    // order is already persisted so a claim failure is logged, not thrown).
-    if ((group[0]?.product?.listingType ?? "standard") === "digital-code") {
-        claimDigitalCodeForOrder(getAdminDb(), firstItem.productId, order.id, uid, {
-            userEmail: userEmail || undefined,
-            userName,
-            productTitle: firstItem.productTitle,
-        }).catch((e) => serverLogger.error("claimDigitalCode", { error: normalizeError(e).message }));
-    }
-    for (const code of groupCouponCodes) {
-        const entry = couponUsageAccumulator.get(code);
-        if (entry)
-            entry.orderIds.push(order.id);
-    }
-    if (userEmail) {
-        emailsToSend.push({
-            to: userEmail,
-            userName,
-            orderId: order.id,
-            productTitle: orderItems.length > 1 ? `${orderItems.length} items` : firstItem.productTitle,
-            quantity: totalQuantity,
-            totalPrice: orderTotal,
-            currency: firstItem.currency ?? getDefaultCurrency(),
-            shippingAddress,
-            paymentMethod: PaymentMethodValues.ONLINE,
-            items: orderItems,
-        });
-    }
-    emitOrderPlacedNotifications({
+    await finalizeOrderPlacement({
         orderId: order.id,
-        buyerUid: uid,
-        buyerName: userName,
+        uid,
+        group,
+        pointsApplied,
+        pointsBudget,
+        firstItem,
+        userEmail,
+        userName,
+        groupCouponCodes,
+        couponUsageAccumulator,
+        emailsToSend,
+        orderItems,
+        totalQuantity,
+        orderTotal,
+        shippingAddress,
+        paymentMethod: PaymentMethodValues.ONLINE,
         storeOwnerId,
-        productLabel: orderItems.length > 1 ? `${orderItems.length} items` : firstItem.productTitle,
         paid: true,
         storeId: order.storeId,
     });
@@ -3082,6 +3785,28 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
     const outOfStockPolicy = input.outOfStockPolicy ??
         intent?.outOfStockPolicy ??
         OutOfStockPolicyValues.CANCEL_ORDER;
+    /*
+     * ── ITEM 1.39 — THE CONSENT, RESOLVED NOT RE-TAKEN ────────────────────────
+     *
+     * On this path the money is ALREADY CAPTURED, so there is nothing left to
+     * gate: asking for consent here would be asking a buyer whose card has been
+     * charged whether they agree. The enforcement therefore happens one request
+     * earlier, in `POST /api/payment/create-order`, which writes a
+     * `buyerPolicyConsents` record BEFORE calling the gateway and packs its id
+     * into the gateway's own passthrough channel.
+     *
+     * What this line does is read that record back and prove it belongs to this
+     * buyer. Its failure mode is deliberately 5xx rather than 4xx (see
+     * `POLICY_CONSENT_UNRESOLVED_CODE`): a missing record means our own
+     * pre-capture write is unreadable, not that the buyer did anything wrong, so
+     * the honest answer is "ask us again" — which makes the gateway's retry
+     * schedule the recovery path. The one outcome that is not permitted is
+     * placing an order with no consent record on it.
+     */
+    const policyConsent = await loadBuyerPolicyConsent({
+        consentId: intent?.policyConsentId,
+        uid,
+    });
     // Add-on fees are no longer resolved here. They are per store, and this
     // function has no single store — each group reads its own selection off
     // `cart.storeAddons` inside createPhonePeGroupOrder.
@@ -3167,6 +3892,70 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         const product = productByIdPaid.get(firstMember) ?? null;
         return { item, product };
     });
+    /*
+     * ── Phase 1c at SETTLE: resolve and RECORD. Deliberately does NOT throw. ──
+     *
+     * 🛑 THIS IS THE ONE PLACE THE FAIL-CLOSED RULE MUST NOT REFUSE, and the
+     * reason is arithmetic rather than taste. By the time this runs the gateway
+     * has already captured — the `status !== "paid"` check above is what let us
+     * get here. The funds have therefore already settled wherever the collecting
+     * gateway settles them, so throwing does not un-commingle anything: it only
+     * denies the buyer the order their money has already paid for. That is the
+     * money-taken/no-order failure class this function carries two separate 🛑
+     * blocks about (the `ADDRESS_REQUIRED` tombstone, `order_TqJvzY4gVjR2cc`,
+     * ₹2,511.80 and a manual refund).
+     *
+     * The enforcement point is CAPTURE — `/api/payment/create-order` and the
+     * `"online"` branch of `createCheckoutOrderAction`, both of which refuse
+     * before a payment session exists. This is the detector for the case those
+     * two did not cover: the cart can gain another seller's line between the
+     * capture request and this one (`assertCanAddNewItems` only blocks adding
+     * while a HIGHER lane is pending, so a standard line can still arrive), and
+     * the webhook path reaches here with no session at all.
+     *
+     * So the obligation here is VISIBILITY. A multi-vendor order collected by a
+     * gateway that cannot split means the platform now owes those vendors a
+     * payout from its own balance — a compliance incident an operator has to
+     * know about and resolve out of band. Silently placing the order and saying
+     * nothing is what makes that invisible, and invisible is the whole failure
+     * mode: a commingled capture looks exactly like a successful checkout.
+     *
+     * Best-effort on purpose — neither the log nor the notification may fail a
+     * placement whose payment has already been taken.
+     */
+    const settlementCheck = resolveCollectingGatewayForCart({
+        items: settleItems,
+        productById: productByIdPaid,
+        platformStoreId: siteSettings?.payment?.platformStoreId,
+    });
+    if (!settlementCheck.resolution.ok) {
+        const collectingGateway = getProviders().payment?.name ?? "unknown";
+        serverLogger.error("SETTLEMENT COMPLIANCE: a captured payment was settled by a gateway that cannot satisfy this cart", {
+            merchantOrderId,
+            gateway: collectingGateway,
+            constraint: settlementCheck.resolution.failedConstraint ?? "none",
+            detail: settlementCheck.resolution.detail,
+        });
+        await adminNotificationsRepository
+            .create({
+            category: "payouts",
+            title: "Payment collected by a gateway that cannot split this cart",
+            body: `Payment ${merchantOrderId} was captured by "${collectingGateway}" for a cart ` +
+                `that needed more (${settlementCheck.resolution.failedConstraint ?? "no gateway enabled"}). ` +
+                `${settlementCheck.resolution.detail ?? ""} The order is being placed — the buyer has ` +
+                `already paid — but any third-party seller's share is now in the platform's own ` +
+                `account and must be settled manually.`,
+            severity: "error",
+            isRead: false,
+            entityType: "order",
+            entityId: merchantOrderId,
+            audienceUserIds: [],
+        })
+            .catch((notifyErr) => {
+            void normalizeError(notifyErr);
+            serverLogger.error("verifyAndPlaceGatewayOrderAction: failed to write admin notification for a settlement-compliance incident", { merchantOrderId });
+        });
+    }
     // SB6-C — maxPerUser cap check before we touch any state.
     await enforceMaxPerUserForCart({
         userId: uid,
@@ -3248,7 +4037,17 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         // per group — see the same note in `previewCheckoutPricing`. `totalFee`
         // carries the `minimumTransactionFee` floor, and destructuring it away is
         // how it lost every consumer once already (D41).
-        const expectedFees = computeCheckoutFees(cartSubtotalRs, commissionRates);
+        /*
+         * 🛑 `sum(item.quantity)` over the same available set the capture route
+         * priced (`POST /api/payment/create-order` sums its own `activeItems`).
+         * This guard runs AFTER the money has moved, so a count that disagreed with
+         * the capture's would make it expect a different fee and throw on a paid
+         * order — the exact post-capture-throw shape the comment above is about,
+         * which is why the multiplier has to be derived from the same collection
+         * rather than recounted from a different one.
+         */
+        const expectedLineUnits = productChecks.map(({ item }) => item.quantity ?? 0);
+        const expectedFees = computeCheckoutFees(cartSubtotalRs, commissionRates, expectedLineUnits);
         const { platformFee: expectedPlatformFee, gstOnFee: expectedGstOnFee } = expectedFees;
         // Same per-seller-group shipping sum /api/payment/create-order charged
         // upfront (and the same resolveShippingCost createPhonePeGroupOrder
@@ -3389,7 +4188,11 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
                     g.items[0].item.storeId,
                     g.items.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0),
                 ]);
-                const guardFeeByGroup = allocateCheckoutFees(guardSubtotals, expectedFees);
+                // By UNIT COUNT, matching the capture route and both order paths — the
+                // apportionment weight had to change with the fee model, and a guard
+                // weighting it differently would expect a different per-group share.
+                const guardLineUnits = new Map(expectedShippingGroups.map((g) => [g.items[0].item.storeId, g.items.map(({ item }) => item.quantity ?? 0)]));
+                const guardFeeByGroup = allocateCheckoutFees(guardSubtotals, expectedFees, guardLineUnits, commissionRates);
                 const guardCouponByGroup = computeCartCouponDiscount(cart.appliedCoupons ?? [], expectedShippingGroups.map((g) => ({
                     storeId: g.items[0].item.storeId,
                     lines: g.items.map(({ item, product }) => ({
@@ -3499,11 +4302,15 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
     const cartSubtotal = orderGroups.reduce((s, { items: g }) => s +
         g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
-    // Same single capped commission + pro-rata split as the COD/UPI path.
+    // Same tapered per-unit fee + exact per-store split as the COD/UPI path.
+    const gatewayCommissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
+    const gatewayLineUnitsOf = (g) => g.map(({ item }) => item.quantity ?? 0);
+    const gatewayLineUnitsByStore = new Map(orderGroups.map(({ items: g }) => [g[0].item.storeId, gatewayLineUnitsOf(g)]));
+    const gatewayCartLineUnits = orderGroups.flatMap(({ items: g }) => gatewayLineUnitsOf(g));
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
         g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
-    ]), computeCheckoutFees(cartSubtotal, siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS));
+    ]), computeCheckoutFees(cartSubtotal, gatewayCommissions, gatewayCartLineUnits), gatewayLineUnitsByStore, gatewayCommissions);
     /*
      * The points budget for this checkout — one read, zero when not opted in.
      * See the identical pair in the COD/manual path for why it is a shared
@@ -3517,18 +4324,49 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
      */
     const useAllPoints = cart.useAllPoints === true;
     const pointsBudget = { remaining: useAllPoints ? await safePointsBalance(uid) : 0 };
+    /*
+     * ── What the gateway was INSTRUCTED to settle to each vendor ──────────────
+     *
+     * One bounded single-field query for the whole capture, so each order can
+     * record whether ITS seller's share went straight to them out of escrow.
+     * That record is the double-payment guard: without it the payout sweeps would
+     * later create a full payout for a share the aggregator has already settled.
+     *
+     * 🛑 READ, never recomputed. The instruction was built in the capture request
+     * (`/api/payment/create-order`), which is the only place that held the vendor
+     * registrations and the exact amounts. The cart can gain a line between that
+     * request and this one — which is exactly why the settlement-compliance
+     * detector above exists — so a recomputation here would quietly disagree with
+     * what was actually sent.
+     *
+     * 🛑 Best-effort: an unreadable payout row must not fail a placement whose
+     * payment has already been taken (the money-taken/no-order class this
+     * function carries two 🛑 blocks about). An empty map means "no split
+     * recorded", which routes the order down the ORDINARY payout path — a seller
+     * chasing a late payout is recoverable; one whose order wrongly claims it was
+     * already settled would never be paid at all.
+     */
+    let splitByStore = new Map();
+    try {
+        splitByStore = await payoutRepository.findBySettlementReference(merchantOrderId);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.error("verifyAndPlaceGatewayOrderAction: could not read the split-settlement records for this capture — orders will be placed on the ORDINARY payout path", { merchantOrderId, error: normalized.message });
+    }
     for (const { items: group, orderType } of orderGroups) {
         total += await createPhonePeGroupOrder(group, orderType, {
             appliedCoupons,
             cartSubtotal,
             storeAddons: cart.storeAddons,
             platformFeeByStore,
+            policyConsent,
             siteSettings,
             uid,
             userName,
             userEmail,
             merchantOrderId,
-            phonepeOrderId: gatewayOrder.gatewayOrderId,
+            gatewayOrderId: gatewayOrder.gatewayOrderId,
             transactionId: gatewayOrder.transactionId,
             shippingAddress,
             /*
@@ -3568,8 +4406,16 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
              */
             emiOptIn: cart.emiPlan?.tenureMonths !== undefined,
             emiTenureMonths: cart.emiPlan?.tenureMonths,
+            splitByStore,
         });
     }
+    /*
+     * Item 1.39 — backlink, same as the COD/manual path. On THIS path it carries
+     * extra diagnostic weight: a consent record with a captured payment behind it
+     * and no order ids is the 2026-10-21 shape (money taken, no order), so the
+     * absence of this link is itself a signal worth being able to query for.
+     */
+    await attachOrdersToPolicyConsent(policyConsent.consentId, orderIds);
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);
     // SB-UNI-5 2026-05-13 — bundle-aware batch decrement. We iterate the
     // cumulative `decrements` map (one entry per unique member product) so a