@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/shared/checkout/order-math.js

@@ -1,5 +1,13 @@
 import { roundRupees } from "../../../utils/number.formatter.js";
 import { calculateGstInclusive, taxableFromInclusive } from "../fees/calculator.js";
+/*
+ * Points: the CAP arithmetic only. `maxRedeemablePoints` lives beside
+ * `POINTS_MAX_REDEMPTION_PERCENT`, which is the constant that defines it, so
+ * importing it here keeps one owner for the rule rather than a second copy of
+ * the percentage (Root Cause #75). This file stays pure — the points SCHEMA is
+ * plain data with no Firestore import.
+ */
+import { maxRedeemablePoints } from "../../../features/points/schemas/firestore.js";
 /**
  * The single source of truth for "what do we charge for ONE COPY of this line".
  *
@@ -593,14 +601,165 @@ export function orderPointsFunded(order) {
         ? roundRupees(Math.max(0, awarded))
         : 0;
 }
+/**
+ * Points this order CONSUMED, which the accepting store also funds (D46/D47).
+ *
+ * Decision 3's other end. The earn above is borne by the originating store;
+ * the redemption is absorbed by the store that agreed to accept points
+ * (`StoreDocument.acceptsPoints`, defaulting to NOT accepted precisely so no
+ * seller is enrolled in funding discounts they never agreed to). The platform
+ * funds neither end.
+ *
+ * Reads `pointsApplied` off the order for the same reason the earn reads
+ * `pointsAwarded`: it must be what was actually spent. Recomputing the cap from
+ * today's total would deduct a figure the buyer never received the benefit of —
+ * and on a partially-cancelled order the total has moved.
+ */
+export function orderPointsRedeemed(order) {
+    const applied = order.pointsApplied;
+    return typeof applied === "number" && Number.isFinite(applied)
+        ? roundRupees(Math.max(0, applied))
+        : 0;
+}
 /** Sum of `orderPointsFunded` across a batch. */
 export function ordersPointsFunded(orders) {
     return roundRupees(orders.reduce((sum, o) => sum + orderPointsFunded(o), 0));
 }
+/**
+ * Everything the store funds through the points programme, for one batch:
+ * points ISSUED on these orders plus points SPENT on them.
+ *
+ * ## 🛑 One figure, because they are one obligation
+ *
+ * Both ends are seller-funded (decisions 3 and 17) and both are deducted from
+ * the same payout at the same moment, so splitting them across two parameters
+ * of `computePayoutDeduction` would be two chances for a call site to pass one
+ * and forget the other — and a payout that deducts the earn but not the
+ * redemption is short by exactly the amount nobody noticed.
+ *
+ * 🛑 This helper exists because `ordersPointsFunded` had **ZERO consumers**
+ * from the day it was written — the earn deduction was built, documented at
+ * length, and never passed to the function it was built for, so every payout
+ * since has quietly been funded by the platform. That is the dead-field
+ * pattern (Rule: every declared field has both a writer and a reader) occurring
+ * inside the work that catalogues it. Wiring the combined figure at all four
+ * call sites is what closes it.
+ */
+export function ordersPointsBorneByStore(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderPointsFunded(o) + orderPointsRedeemed(o), 0));
+}
 /** Sum of `orderShippingReimbursement` across a batch. */
 export function ordersShippingReimbursement(orders) {
     return roundRupees(orders.reduce((sum, o) => sum + orderShippingReimbursement(o), 0));
 }
+/**
+ * How many points may be spent on ONE order group, and what is left to charge.
+ *
+ * ## 🛑 A PIPELINE STAGE, after the final rounding — never a post-order debit
+ *
+ * This is the whole lesson of D46. The deleted code redeemed points AFTER the
+ * orders existed and the gateway had captured `orderTotal`, so a successful
+ * redemption took points from a buyer who had just paid full price: nothing in
+ * the pipeline knew about the spend, so nothing reduced the charge.
+ *
+ * So the tender is a STAGE. `amountDue = orderTotal − pointsApplied` is
+ * computed here, and `amountDue` is what the gateway captures and what the
+ * post-capture guard compares. A sixth way for the captured amount to diverge
+ * from the recorded total is the D37/D38/D40 family; this is how it is avoided.
+ *
+ * ## 🛑 Applied AFTER rounding, deliberately
+ *
+ * `orderTotal` is rounded ONCE at the end of its own nine-term sum (D42).
+ * Folding points in before that rounding would put a discount inside the sum
+ * being rounded, so the figure shown to the buyer and the figure captured could
+ * differ by a paisa. They must be provably equal, which is why `amountDue` is
+ * derived here and never recomputed at the gateway.
+ *
+ * ## Per order group, because the ACCEPTING STORE absorbs it
+ *
+ * Decision 3: a redeemed point reduces THAT store's payout for THAT order. A
+ * cart spanning an accepting and a non-accepting store must not pool the
+ * discount — each group gets its own cap and its own figure. That is the same
+ * granularity `splitCartIntoOrderGroups` and `allocateCheckoutFees` already
+ * use, and its absence is what caused Root Cause #65's per-store
+ * multiplication bug.
+ *
+ * ## All-or-nothing, and the remainder STAYS
+ *
+ * Owner's rule: *"if use point it is all and then the balance is returned if
+ * excess"*. There is no requested amount — the balance is spent down as far as
+ * the cap allows, and whatever will not fit is simply not spent. It stays in
+ * the ledger for a later order; nothing is forfeited, and no caller can ask for
+ * a partial spend.
+ *
+ * 🛑 The 50% cap is not optional, and removing it was explicitly declined.
+ * `POINTS_MAX_REDEMPTION_PERCENT` exists because a ₹0 order breaks the gateway
+ * (a ₹0 Razorpay order is not a thing) and because a balance that can settle a
+ * whole purchase behaves like the stored value the points schema is written to
+ * avoid.
+ */
+export function resolvePointsTender(input) {
+    const total = roundRupees(Math.max(0, input.orderTotal));
+    if (!input.optedIn || !input.accepted)
+        return { pointsApplied: 0, amountDue: total };
+    const balance = Math.floor(Math.max(0, input.balance));
+    if (!Number.isFinite(balance) || balance <= 0)
+        return { pointsApplied: 0, amountDue: total };
+    /*
+     * `maxRedeemablePoints` owns the cap arithmetic — it floors to whole points
+     * and applies `POINTS_MAX_REDEMPTION_PERCENT`. Re-deriving the percentage
+     * here would be a second copy of a money rule (Root Cause #75), and the one
+     * place it already lives sits beside the constant that defines it.
+     */
+    const pointsApplied = maxRedeemablePoints(total, balance);
+    return { pointsApplied, amountDue: roundRupees(total - pointsApplied) };
+}
+/**
+ * The payable total a points allocation is measured against.
+ *
+ * 🛑 ONE implementation, because it was two. `POST /api/payment/create-order`
+ * and `verifyAndPlaceRazorpayOrderAction`'s amount guard each built this sum
+ * by hand, in the same shape, from the same six parts — and they are the
+ * *shown* figure and the *charged* figure for the same cart. Two hand-written
+ * copies of one money rule is Root Cause #75 exactly, and the failure mode is
+ * the worst kind: they only disagree on carts where the arithmetic differs, so
+ * nothing errors and the buyer is quoted one number and charged another.
+ *
+ * The coupon is floored at zero before the fees are added, never after — a
+ * discount larger than the goods must not eat the shipping and platform fee.
+ */
+export function pointsBaseForGroup(parts) {
+    return {
+        total: roundRupees(Math.max(0, parts.goods - parts.couponDiscount) +
+            parts.shippingFee +
+            parts.addonFee +
+            parts.platformFee +
+            parts.gstOnFee),
+        accepted: parts.acceptsPoints,
+    };
+}
+export function allocatePointsAcrossGroups(groups, balance, optedIn) {
+    const perGroup = groups.map(() => 0);
+    if (!optedIn)
+        return { perGroup, pointsApplied: 0 };
+    let remaining = Math.floor(Math.max(0, balance));
+    if (!Number.isFinite(remaining) || remaining <= 0)
+        return { perGroup, pointsApplied: 0 };
+    let applied = 0;
+    for (let i = 0; i < groups.length; i += 1) {
+        const g = groups[i];
+        const { pointsApplied } = resolvePointsTender({
+            orderTotal: g.total,
+            balance: g.accepted ? remaining : 0,
+            accepted: g.accepted,
+            optedIn: true,
+        });
+        perGroup[i] = pointsApplied;
+        remaining -= pointsApplied;
+        applied += pointsApplied;
+    }
+    return { perGroup, pointsApplied: applied };
+}
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one

package/dist/_internal/shared/checkout/refundable-base.d.ts

@@ -36,6 +36,21 @@ export interface RefundableOrderLike {
         amount: number;
         status?: string;
     }>;
+    /**
+     * D46/D47 — points applied at checkout, in points (1 point = ₹1).
+     *
+     * 🛑 Subtracted from the refundable base, because **a refund can only return
+     * money that was collected.** On a ₹1,000 order settled with 250 points the
+     * card was charged ₹750; refunding the full base would hand the buyer ₹1,000
+     * and then `reverseRedemptionForOrder` would hand back 250 points on top —
+     * ₹250 of real money created out of a discount.
+     *
+     * The points themselves come back as POINTS, never as cash. That is not a
+     * stylistic choice: `pointsLedger`'s header states it as a legal boundary,
+     * because paying a balance out in rupees is what makes it stored value, which
+     * in India is PPI territory with RBI authorisation attached.
+     */
+    pointsApplied?: number;
 }
 /**
  * The platform fee actually withheld on a refund: the amount CHARGED, never a
@@ -77,6 +92,16 @@ legacyGstPercent?: number): number;
  * has to compare against THIS, or the largest possible refund is strictly less
  * than `totalPrice` and **an order can never reach `status: "refunded"`** —
  * which is what the old `amount >= totalPrice` test guaranteed.
+ *
+ * 🛑 And `pointsApplied` comes off too (D46/D47). A refund returns MONEY, and
+ * the money collected was `totalPrice − pointsApplied`; the points go back
+ * through `reverseRedemptionForOrder` as points. Leaving them in the base would
+ * refund them twice — once in rupees here and once in points there — which is
+ * the one way this feature could manufacture real money from a discount.
+ *
+ * Absent means zero, so every order written before the tender existed is
+ * unaffected, and `isFull` still reaches the exhausted state on them exactly as
+ * before.
  */
 export declare function refundableBase(order: RefundableOrderLike, legacyGstPercent?: number): number;
 /**

package/dist/_internal/shared/checkout/refundable-base.js

@@ -75,9 +75,21 @@ legacyGstPercent) {
  * has to compare against THIS, or the largest possible refund is strictly less
  * than `totalPrice` and **an order can never reach `status: "refunded"`** —
  * which is what the old `amount >= totalPrice` test guaranteed.
+ *
+ * 🛑 And `pointsApplied` comes off too (D46/D47). A refund returns MONEY, and
+ * the money collected was `totalPrice − pointsApplied`; the points go back
+ * through `reverseRedemptionForOrder` as points. Leaving them in the base would
+ * refund them twice — once in rupees here and once in points there — which is
+ * the one way this feature could manufacture real money from a discount.
+ *
+ * Absent means zero, so every order written before the tender existed is
+ * unaffected, and `isFull` still reaches the exhausted state on them exactly as
+ * before.
  */
 export function refundableBase(order, legacyGstPercent) {
-    return roundRupees(Math.max(0, order.totalPrice - platformFeeWithheld(order, legacyGstPercent)));
+    return roundRupees(Math.max(0, order.totalPrice -
+        platformFeeWithheld(order, legacyGstPercent) -
+        Math.max(0, order.pointsApplied ?? 0)));
 }
 /**
  * Sum of refunds that have COMMITTED money, i.e. everything not `failed`.

package/dist/_internal/shared/checkout/rules/index.d.ts

@@ -1,6 +1,6 @@
 export type { ListingCheckoutRule, CategoryCheckoutRule, CartItemProductPair, OrderItemInput, RefundPolicy, } from "./types";
 export { CHECKOUT_RULES, CATEGORY_CHECKOUT_RULES, getListingRule, getCategoryRule, pickOrderType, getSplitKey, runSyncPreflight, } from "./_registry";
-export { assertPaymentMethodAllowed, blockedMethodsForCart, type BlockedMethod, } from "./payment-gate";
+export { assertPaymentMethodAllowed, assertEmiOptInAllowed, blockedMethodsForCart, type BlockedMethod, } from "./payment-gate";
 export { CART_MAX_ITEMS, CHECKOUT_MAX_ORDERS_PER_TX, PRIZE_DRAW_MAX_REVEALS_PER_ORDER, PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, BUNDLE_MAX_QTY_PER_TX, STANDARD_MAX_QTY_PER_LINE, } from "./_limits";
 export { standardRule } from "./standard.rule";
 export { auctionRule } from "./auction.rule";

package/dist/_internal/shared/checkout/rules/index.js

@@ -6,7 +6,7 @@ export { CHECKOUT_RULES, CATEGORY_CHECKOUT_RULES, getListingRule, getCategoryRul
  * apart is what stops someone folding it back into preflight, where it would
  * silently stop covering bundles and grouped lines.
  */
-export { assertPaymentMethodAllowed, blockedMethodsForCart, } from "./payment-gate.js";
+export { assertPaymentMethodAllowed, assertEmiOptInAllowed, blockedMethodsForCart, } from "./payment-gate.js";
 export { CART_MAX_ITEMS, CHECKOUT_MAX_ORDERS_PER_TX, PRIZE_DRAW_MAX_REVEALS_PER_ORDER, PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, BUNDLE_MAX_QTY_PER_TX, STANDARD_MAX_QTY_PER_LINE, } from "./_limits.js";
 // Individual rules — exported for tests and direct access.
 export { standardRule } from "./standard.rule.js";

package/dist/_internal/shared/checkout/rules/payment-gate.d.ts

@@ -24,3 +24,21 @@ export declare function blockedMethodsForCart(items: readonly CartItemDocument[]
  * decision.
  */
 export declare function assertPaymentMethodAllowed(items: readonly CartItemDocument[], productById: ReadonlyMap<string, ProductDocument>, paymentMethod: CheckoutPaymentMethod | undefined): void;
+/**
+ * Throw when anything in the cart forbids an instalment plan.
+ *
+ * 🛑 Reads the SAME `blockedPaymentMethods` declaration, under the key
+ * `"emi"`, rather than introducing a parallel `blocksEmi` field. The listing
+ * rules already say "this listing type cannot be paid in instalments" — they
+ * said it by naming a payment method, because that is what EMI was. Once EMI
+ * became an order-level opt-in, that declaration needed a second reader, not
+ * a second declaration: a rule stated twice is a rule that drifts (Root Cause
+ * #61), and `prizeDrawRule`'s entry would otherwise have gone inert the day
+ * the tender disappeared.
+ *
+ * `blockedPaymentMessage` is reused verbatim for the same reason the gate
+ * above prefers it to a generated sentence: it names the REASON (winner
+ * assignment waits on confirmed payment), which is what lets a buyer choose
+ * differently instead of abandoning.
+ */
+export declare function assertEmiOptInAllowed(items: readonly CartItemDocument[], productById: ReadonlyMap<string, ProductDocument>, emiOptIn: boolean): void;

package/dist/_internal/shared/checkout/rules/payment-gate.js

@@ -131,3 +131,28 @@ export function assertPaymentMethodAllowed(items, productById, paymentMethod) {
         ? `${offender.message} Available instead: ${allowed.join(", ")}.`
         : `${offender.message} Nothing in this cart's combination can be paid for — remove the item and buy it on its own.`), { code: "PAYMENT_METHOD_BLOCKED" });
 }
+/**
+ * Throw when anything in the cart forbids an instalment plan.
+ *
+ * 🛑 Reads the SAME `blockedPaymentMethods` declaration, under the key
+ * `"emi"`, rather than introducing a parallel `blocksEmi` field. The listing
+ * rules already say "this listing type cannot be paid in instalments" — they
+ * said it by naming a payment method, because that is what EMI was. Once EMI
+ * became an order-level opt-in, that declaration needed a second reader, not
+ * a second declaration: a rule stated twice is a rule that drifts (Root Cause
+ * #61), and `prizeDrawRule`'s entry would otherwise have gone inert the day
+ * the tender disappeared.
+ *
+ * `blockedPaymentMessage` is reused verbatim for the same reason the gate
+ * above prefers it to a generated sentence: it names the REASON (winner
+ * assignment waits on confirmed payment), which is what lets a buyer choose
+ * differently instead of abandoning.
+ */
+export function assertEmiOptInAllowed(items, productById, emiOptIn) {
+    if (!emiOptIn)
+        return;
+    const offender = blockedMethodsForCart(items, productById).get("emi");
+    if (!offender)
+        return;
+    throw Object.assign(new ValidationError(`${offender.message} Pay for this order in full instead, or remove the item and buy it on its own.`), { code: "EMI_NOT_ALLOWED" });
+}

package/dist/_internal/shared/checkout/split.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Group-purchase contribution splits — the ONE owner of the invariant.
+ *
+ * A coordinator divides what a grouped line costs among its members. They may
+ * type absolute amounts or percentages, and the total may come out at or ABOVE
+ * the landed cost; the excess belongs to the seller.
+ *
+ * ## The invariant
+ *
+ * ```
+ * landedCost = goods + shipping + fees + add-ons        (per order group)
+ *
+ * contribution(member) = percent × landedCost   OR   a typed amount
+ * require:  Σ(contributions) ≥ landedCost
+ * surplus:  Σ(contributions) − landedCost
+ * ```
+ *
+ * Percentages summing above 100% and typed amounts summing above the landed
+ * cost are **the same case**, so one rule covers both and there is no
+ * mode-specific branch to get wrong.
+ *
+ * ## Why the surplus becomes `lockedPrice`
+ *
+ * `unitPriceFor` already honours `lockedPrice` ahead of everything else — that
+ * is how an accepted offer BELOW list is charged correctly. An agreed total
+ * ABOVE list is the same mechanism in the other direction, so GST is charged on
+ * what was actually paid, the payout base rises by the surplus,
+ * `refundableBase` ceilings at the agreed amount, and the invoice needs no new
+ * line. No new money term anywhere.
+ */
+/** A member's share, as the coordinator expressed it. */
+export interface SplitContribution {
+    productId: string;
+    /** `"percent"` reads `percent`; `"amount"` reads `amount`. */
+    splitMode: "amount" | "percent";
+    /** 0–100. Required when `splitMode === "percent"`. */
+    percent?: number;
+    /** Decimal rupees. Required when `splitMode === "amount"`. */
+    amount?: number;
+}
+export interface SplitResolution {
+    /** Per member, in input order, after rounding. */
+    resolved: Array<{
+        productId: string;
+        amount: number;
+    }>;
+    /** What the members together put in. */
+    contributed: number;
+    /** `contributed − landedCost`, never negative (see `shortfall`). */
+    surplus: number;
+    /** `landedCost − contributed` when the split is short, else 0. */
+    shortfall: number;
+    /** The invariant holds. A caller must refuse to commit when false. */
+    valid: boolean;
+}
+export declare function resolveSplit(contributions: readonly SplitContribution[], landedCost: number): SplitResolution;
+/**
+ * The price to lock on the line, given the goods subtotal and a surplus.
+ *
+ * ## 🛑 THE TRAP THIS FUNCTION EXISTS TO PREVENT
+ *
+ * The percentage BASE is the landed cost — goods **plus shipping plus fees** —
+ * because that is what the coordinator is really dividing. But `lockedPrice` is
+ * the GOODS price of the line: the checkout adds shipping, the platform fee,
+ * GST and the add-ons on top of it, independently.
+ *
+ * So locking the landed cost would charge shipping and every fee **TWICE** —
+ * once inside `lockedPrice` and once again as the checkout's own terms. The
+ * surplus rides on the goods price alone.
+ *
+ * That is the whole reason this is a named function rather than an expression
+ * at a call site: `goods + surplus` and `landedCost + surplus` are both
+ * plausible-looking one-liners and only one of them is a correct charge.
+ */
+export declare function lockedPriceWithSurplus(goodsSubtotal: number, surplus: number): number;

package/dist/_internal/shared/checkout/split.js

@@ -0,0 +1,120 @@
+/**
+ * Group-purchase contribution splits — the ONE owner of the invariant.
+ *
+ * A coordinator divides what a grouped line costs among its members. They may
+ * type absolute amounts or percentages, and the total may come out at or ABOVE
+ * the landed cost; the excess belongs to the seller.
+ *
+ * ## The invariant
+ *
+ * ```
+ * landedCost = goods + shipping + fees + add-ons        (per order group)
+ *
+ * contribution(member) = percent × landedCost   OR   a typed amount
+ * require:  Σ(contributions) ≥ landedCost
+ * surplus:  Σ(contributions) − landedCost
+ * ```
+ *
+ * Percentages summing above 100% and typed amounts summing above the landed
+ * cost are **the same case**, so one rule covers both and there is no
+ * mode-specific branch to get wrong.
+ *
+ * ## Why the surplus becomes `lockedPrice`
+ *
+ * `unitPriceFor` already honours `lockedPrice` ahead of everything else — that
+ * is how an accepted offer BELOW list is charged correctly. An agreed total
+ * ABOVE list is the same mechanism in the other direction, so GST is charged on
+ * what was actually paid, the payout base rises by the surplus,
+ * `refundableBase` ceilings at the agreed amount, and the invoice needs no new
+ * line. No new money term anywhere.
+ */
+import { roundRupees } from "../../../utils/number.formatter.js";
+/**
+ * Resolve contributions against a landed cost.
+ *
+ * Pure. No I/O, no clock — the landed cost is computed by the caller from the
+ * order group it already has.
+ *
+ * 🛑 ROUNDS ONCE, at the end of each member's amount, and then puts the
+ * ROUNDING REMAINDER on the last member. Rounding each percentage
+ * independently and summing is how a 3-way 33.33% split charges a rupee less
+ * than the agreed total and the surplus silently goes negative — the same
+ * remainder discipline `allocateAcrossMembers` uses for bundle tax.
+ */
+/**
+ * `percent` of `amount`, where `percent` is 0–100.
+ *
+ * 🛑 A NAMED HELPER rather than the division written inline, for legibility
+ * to a reader AND to `audit-money-units`. That audit flags a scale division
+ * beside a money identifier because it is the exact shape of the 2026-05
+ * minor-unit bug — a conversion left behind by a migration — and a
+ * percentage conversion is visually identical to it. Two such lines are two
+ * judgement calls; one helper is a single place to establish that this
+ * divisor is about PERCENTAGES and never about currency scale.
+ *
+ * 🛑 That audit reads COMMENTS as well as code, so this one cannot quote the
+ * expression it is about: a worked example of the shape is indistinguishable
+ * from the shape. Reading comments is correct of it — a stale "stored in
+ * minor units" remark in prose is one of the things it hunts, and Root Cause
+ * #87 is the opposite mistake, an audit that stripped comments and so
+ * counted a commented-out registration as live.
+ */
+// audit-money-units-ok: a percent-to-fraction conversion, not a minor-unit conversion
+const applyPercent = (percent, amount) => (percent / 100) * amount;
+export function resolveSplit(contributions, landedCost) {
+    const resolved = [];
+    for (const c of contributions) {
+        const raw = c.splitMode === "percent" ? applyPercent(c.percent ?? 0, landedCost) : (c.amount ?? 0);
+        resolved.push({ productId: c.productId, amount: roundRupees(raw) });
+    }
+    /*
+     * The remainder goes on the LAST member rather than being spread, so the
+     * parts reconcile to the total exactly and the discrepancy is one member's
+     * single rupee rather than a fraction on everybody.
+     *
+     * Only for a pure PERCENT split: typed amounts are what the coordinator
+     * actually said, and silently adjusting one of them would charge somebody a
+     * figure they did not enter.
+     */
+    const allPercent = contributions.every((c) => c.splitMode === "percent");
+    if (allPercent && resolved.length > 0) {
+        const pctTotal = contributions.reduce((s, c) => s + (c.percent ?? 0), 0);
+        const target = roundRupees(applyPercent(pctTotal, landedCost));
+        const sum = resolved.reduce((s, r) => s + r.amount, 0);
+        const drift = roundRupees(target - sum);
+        if (drift !== 0) {
+            const last = resolved[resolved.length - 1];
+            resolved[resolved.length - 1] = { ...last, amount: roundRupees(last.amount + drift) };
+        }
+    }
+    const contributed = roundRupees(resolved.reduce((s, r) => s + r.amount, 0));
+    const diff = roundRupees(contributed - landedCost);
+    return {
+        resolved,
+        contributed,
+        surplus: diff > 0 ? diff : 0,
+        shortfall: diff < 0 ? -diff : 0,
+        valid: diff >= 0,
+    };
+}
+/**
+ * The price to lock on the line, given the goods subtotal and a surplus.
+ *
+ * ## 🛑 THE TRAP THIS FUNCTION EXISTS TO PREVENT
+ *
+ * The percentage BASE is the landed cost — goods **plus shipping plus fees** —
+ * because that is what the coordinator is really dividing. But `lockedPrice` is
+ * the GOODS price of the line: the checkout adds shipping, the platform fee,
+ * GST and the add-ons on top of it, independently.
+ *
+ * So locking the landed cost would charge shipping and every fee **TWICE** —
+ * once inside `lockedPrice` and once again as the checkout's own terms. The
+ * surplus rides on the goods price alone.
+ *
+ * That is the whole reason this is a named function rather than an expression
+ * at a call site: `goods + surplus` and `landedCost + surplus` are both
+ * plausible-looking one-liners and only one of them is a correct charge.
+ */
+export function lockedPriceWithSurplus(goodsSubtotal, surplus) {
+    return roundRupees(goodsSubtotal + surplus);
+}

package/dist/_internal/shared/content/disclaimers.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Disclaimers — one registry, rendered by `<Disclaimer id>` (Phase 12).
+ *
+ * ## 🛑 Why a registry and not a sentence per surface
+ *
+ * Same failure mode as the published numbers in Phase 9: if each surface
+ * writes its own, they drift, and **the legally material ones end up
+ * weakest** — because the surface that most needs a careful disclaimer is
+ * usually the one whose author was busiest. The scam registry is the example:
+ * naming a person a scammer is defamation exposure, and it had no disclaimer
+ * at all.
+ *
+ * ## The three rules every entry obeys
+ *
+ * 1. **Visible BEFORE the decision it qualifies**, not only on a policy page
+ *    reachable from the footer. The protection disclaimer belongs beside the
+ *    checkbox, not in `/refund-policy`.
+ * 2. **It names a LIMIT or an EXCLUSION.** A disclaimer that only says "we
+ *    try our best" qualifies nothing and is worse than none — it reads as
+ *    cover while providing none.
+ * 3. **It AGREES with the code.** Limits render from the constants that
+ *    enforce them (`SALE_PROTECTION_MAX_VALUE`, the claim windows), through
+ *    the same `{{token}}` mechanism as Phase 9, so a constant change updates
+ *    the published terms rather than contradicting them.
+ *
+ * ## 🛑 NOT a cookie-banner blanket
+ *
+ * A disclaimer that appears everywhere is read nowhere. Each entry names the
+ * specific surfaces that need it, and `audit-disclaimer-coverage` checks those
+ * surfaces render one — not that every page does.
+ */
+export type DisclaimerId = 
+/** Naming a person a scammer. The highest-exposure entry in this file. */
+"scam-registry"
+/** Prize draws and the lottery — state-specific gaming law. */
+ | "prize-draw"
+/** Collectibles shown with historical prices. */
+ | "not-investment-advice"
+/** The realised-price index. */
+ | "price-index"
+/** Authenticity and grading. */
+ | "authenticity"
+/** Buyer protection cover — OUR cover, not insurance. */
+ | "protection-cover"
+/** P&L, trial balance, GSTR-1 draft. */
+ | "accounting-output"
+/** Live animals and plants. */
+ | "live-items"
+/** Pre-orders. */
+ | "pre-order"
+/** Auctions. */
+ | "auction-binding"
+/** EMI. */
+ | "emi"
+/** Delivery estimates. */
+ | "delivery-estimate"
+/** Reviews, catalogue entries, blog comments. */
+ | "user-content"
+/** GST shown on an invoice. */
+ | "tax-computation"
+/** An automated decision — a timer cancelled, approved or completed something. */
+ | "automated-decision";
+export interface DisclaimerEntry {
+    /** Short heading, when the surface renders one. Omit for inline notes. */
+    heading?: string;
+    /**
+     * The text. May contain `{{token}}`s resolved by `resolvePublishedCopy`.
+     *
+     * 🛑 Must name a limit or an exclusion — see rule 2 in the header. An entry
+     * that does not is not a disclaimer, and `audit-disclaimer-coverage` checks
+     * for it rather than trusting the author.
+     */
+    body: string;
+    /**
+     * Tone, which decides the rendered variant.
+     *
+     * `legal` is the quiet grey note; `warning` is the one a user must not scroll
+     * past. 🛑 Reserved for the entries where ignoring it has a consequence the
+     * user cannot undo — not used to make a disclaimer feel important.
+     */
+    tone: "legal" | "warning";
+    /**
+     * Where this must appear, as a free-text note for the reviewer and the
+     * audit's own registry.
+     */
+    surfaces: readonly string[];
+}
+export declare const DISCLAIMERS: Record<DisclaimerId, DisclaimerEntry>;