@mohasinac/appkit 4.62.0 → 4.62.1

package/dist/features/orders/constants/order-lane-tabs.js

@@ -0,0 +1,88 @@
+/**
+ * Order PROVENANCE tabs — the one definition, shared by the buyer's and the
+ * seller's order lists.
+ *
+ * ## Why this file exists
+ *
+ * The buyer's list had these tabs and the seller's did not. A seller could see
+ * every order and could not ask "show me the ones I accepted an offer on" or
+ * "show me the auction wins", which is exactly the split that changes how they
+ * are handled: an auction win has a forfeit deadline, an accepted offer has an
+ * agreed price that is not the listing price.
+ *
+ * Copying the array into the second view would have been the ninth
+ * hand-written enumeration of one union in this codebase (Root Cause #61), so
+ * the labels are a `Record<OrderType, string>` instead: a sixth lane is a
+ * COMPILE error here rather than a tab that silently never appears.
+ *
+ * 🛑 Three things about these ids, each of which has already cost a bug:
+ *
+ * 1. **Every id is EXACTLY a stored `OrderDocument.orderType` value.** Firestore
+ *    `==` is byte-exact, so a tab id that is merely plausible returns zero rows
+ *    forever with no error anywhere (Root Cause #33).
+ *
+ * 2. **`preorder` has NO HYPHEN and that is not a typo to tidy up.** `OrderType`
+ *    spells it `preorder`; `ListingType` spells the same concept `pre-order`.
+ *    Two unions, two spellings, and the tab must match the one actually stored.
+ *
+ * 3. **`standard` must be filtered IN MEMORY, never as a Firestore `==`.**
+ *    Orders written before `orderType` existed carry no such field, and an
+ *    equality excludes every document that lacks it — so the "Normal" tab would
+ *    hide every legacy order while looking like it worked. `mergeOrderScopeFilter`
+ *    and the server-side list both already honour this; see `ORDER_LANE_ALL` for
+ *    the "no filter" sentinel.
+ */
+/**
+ * The "All" tab's id. An empty string rather than a word, so it can never
+ * collide with a real `orderType` value and so `state.orderType ? … : null`
+ * reads as "no filter" at every call site.
+ */
+export const ORDER_LANE_ALL = "";
+/**
+ * 🛑 A `Record<OrderType, string>`, deliberately. Omitting a lane does not
+ * compile, which is the whole point — the buyer's list shipped with four tabs
+ * for five lanes, so pre-order and prize-draw orders were reachable only by
+ * landing on "All" and scrolling.
+ */
+export const ORDER_LANE_LABELS = {
+    standard: "Normal",
+    auction: "Auction wins",
+    offer: "Offer wins",
+    preorder: "Pre-orders",
+    "prize-draw": "Prize draws",
+};
+/**
+ * Display order, listed explicitly rather than taken from `Object.keys`.
+ *
+ * Key order on an object literal is not a contract anyone should rely on for
+ * UI ordering, and the intended order is not alphabetical: it mirrors the
+ * cart's lane PRIORITY (auction > offer > standard — highest obligation
+ * first), with the two schedule-driven lanes after them.
+ */
+const LANE_ORDER = [
+    "standard",
+    "auction",
+    "offer",
+    "preorder",
+    "prize-draw",
+];
+/**
+ * The stored `orderType` values a lane filter may name, for route-side
+ * validation.
+ *
+ * Derived from `ORDER_LANE_LABELS`, so it cannot drift from the tabs. Both
+ * `/api/user/orders` and `/api/store/orders` had — or would have needed — their
+ * own hand-written copy of these five strings; this is the eleventh
+ * enumeration of one union in this codebase collapsed into the union itself
+ * (Root Cause #61).
+ *
+ * 🛑 Validating against it is load-bearing, not hygiene: an unrecognised value
+ * interpolated into a Sieve filter string is a caller-controlled field name
+ * reaching the query builder.
+ */
+export const VALID_ORDER_TYPES = new Set(Object.keys(ORDER_LANE_LABELS));
+/** `All` first, then every lane in `LANE_ORDER`. */
+export const ORDER_LANE_TABS = [
+    { id: ORDER_LANE_ALL, label: "All" },
+    ...LANE_ORDER.map((type) => ({ id: type, label: ORDER_LANE_LABELS[type] })),
+];

package/dist/features/orders/repository/orders.repository.d.ts

@@ -196,6 +196,10 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        orderType: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         giftWrapAddon: {
             canFilter: boolean;
             canSort: boolean;
@@ -404,6 +408,32 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
         status: "failed";
         failureReason?: string;
     }, becomeRefunded?: boolean, ctx?: OrderWriteContext): Promise<OrderDocument>;
+    /**
+     * Stamp a credit-note number onto one settled refund event (Phase 7, 7c).
+     *
+     * ## 🛑 Why this is a repository method and not an inline update
+     *
+     * `refunds[]` is written by re-mapping the whole array, exactly as
+     * `settleRefund` directly above does — because a read-modify-write of
+     * `[...existing, event]` LOSES a concurrent event (D6), and that defect is
+     * just as reachable from a credit-note stamp as from a refund append.
+     * Letting the invoicing feature touch the array directly would reintroduce
+     * it one caller away from the fix.
+     *
+     * It goes through `updateWithHistory` for the same reason every other
+     * mutator here does: the transition guard and the status-history entry live
+     * there, and this is a real recorded event on the order.
+     *
+     * 🛑 A missing refund event is a NO-OP, not a throw. The caller is the
+     * refund settle path, where money has already moved; raising here would turn
+     * a successful refund into a reported failure. See
+     * `issueCreditNoteForRefund`'s own 🛑.
+     */
+    setRefundCreditNote(orderId: string, refundId: string, note: {
+        creditNoteNumber: string;
+        creditNoteIssuedAt: Date;
+        creditNoteStoragePath?: string;
+    }, ctx?: OrderWriteContext): Promise<OrderDocument | null>;
     /**
      * 🛑 LEGACY — prefer `reserveRefund` + `settleRefund`.
      *
@@ -442,6 +472,33 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * `paymentProofUrl != null` filter would silently exclude every doc where
      * the field isn't set at all — the opposite of what's needed here.
      */
+    /**
+     * Orders invoiced within a window — the GSTR-1 export's only query
+     * (Phase 7d).
+     *
+     * ## 🛑 Windowed on `invoiceIssuedAt`, not on the order date
+     *
+     * A COD order placed on 30 March and paid on 2 April is invoiced in the NEW
+     * financial year, and that is the period its tax belongs to. Numbering
+     * happens at the payment transition for exactly this reason, so the invoice
+     * date is the only correct axis — windowing on `orderDate` would file that
+     * order's tax in the year before it was invoiced.
+     *
+     * ## 🛑 It also returns PAID orders with no invoice number, deliberately
+     *
+     * Those are the ones the export must warn about rather than omit — a paid
+     * order silently absent from a tax return is the single error this whole
+     * feature exists to prevent. Firestore cannot OR across two fields, so the
+     * second query is a separate one and the caller merges; the alternative
+     * (one query on `paymentStatus`, filtered in memory) would scan every paid
+     * order ever placed.
+     *
+     * Unbounded `.limit(2000)`: a quarter's orders at this volume is a few
+     * hundred, and an export that silently truncated would understate a tax
+     * return. If this ever saturates, the fix is pagination with an explicit
+     * "more rows exist" signal in the CSV — never a higher cap.
+     */
+    listInvoicedBetween(from: Date, to: Date): Promise<OrderDocument[]>;
     getExpiredPaymentDeadlines(): Promise<Array<{
         id: string;
         ref: DocumentReference;

package/dist/features/orders/repository/orders.repository.js

@@ -783,6 +783,52 @@ class OrderRepository extends BaseRepository {
             reason: ctx?.reason ?? target.reason,
         }, "orderRepository.settleRefund", order);
     }
+    /**
+     * Stamp a credit-note number onto one settled refund event (Phase 7, 7c).
+     *
+     * ## 🛑 Why this is a repository method and not an inline update
+     *
+     * `refunds[]` is written by re-mapping the whole array, exactly as
+     * `settleRefund` directly above does — because a read-modify-write of
+     * `[...existing, event]` LOSES a concurrent event (D6), and that defect is
+     * just as reachable from a credit-note stamp as from a refund append.
+     * Letting the invoicing feature touch the array directly would reintroduce
+     * it one caller away from the fix.
+     *
+     * It goes through `updateWithHistory` for the same reason every other
+     * mutator here does: the transition guard and the status-history entry live
+     * there, and this is a real recorded event on the order.
+     *
+     * 🛑 A missing refund event is a NO-OP, not a throw. The caller is the
+     * refund settle path, where money has already moved; raising here would turn
+     * a successful refund into a reported failure. See
+     * `issueCreditNoteForRefund`'s own 🛑.
+     */
+    async setRefundCreditNote(orderId, refundId, note, ctx) {
+        const order = await this.findById(orderId);
+        if (!order)
+            return null;
+        const existing = order.refunds ?? [];
+        const target = existing.find((r) => r.refundId === refundId);
+        if (!target)
+            return null;
+        // Already numbered — never overwrite. A credit-note number is issued once,
+        // and a second number for one reversal is a permanent gap in the series.
+        if (target.creditNoteNumber)
+            return order;
+        const stamped = existing.map((r) => r.refundId === refundId ? { ...r, ...note } : r);
+        return this.updateWithHistory(orderId, { refunds: stamped, updatedAt: new Date() }, {
+            ...ctx,
+            extraChanges: {
+                creditNote: {
+                    from: null,
+                    to: { refundId, creditNoteNumber: note.creditNoteNumber },
+                },
+            },
+            actor: ctx?.actor ?? { uid: "system:invoicing", role: "system" },
+            reason: ctx?.reason ?? `Credit note ${note.creditNoteNumber} issued`,
+        }, "orderRepository.setRefundCreditNote", order);
+    }
     /**
      * 🛑 LEGACY — prefer `reserveRefund` + `settleRefund`.
      *
@@ -878,6 +924,68 @@ class OrderRepository extends BaseRepository {
      * `paymentProofUrl != null` filter would silently exclude every doc where
      * the field isn't set at all — the opposite of what's needed here.
      */
+    /**
+     * Orders invoiced within a window — the GSTR-1 export's only query
+     * (Phase 7d).
+     *
+     * ## 🛑 Windowed on `invoiceIssuedAt`, not on the order date
+     *
+     * A COD order placed on 30 March and paid on 2 April is invoiced in the NEW
+     * financial year, and that is the period its tax belongs to. Numbering
+     * happens at the payment transition for exactly this reason, so the invoice
+     * date is the only correct axis — windowing on `orderDate` would file that
+     * order's tax in the year before it was invoiced.
+     *
+     * ## 🛑 It also returns PAID orders with no invoice number, deliberately
+     *
+     * Those are the ones the export must warn about rather than omit — a paid
+     * order silently absent from a tax return is the single error this whole
+     * feature exists to prevent. Firestore cannot OR across two fields, so the
+     * second query is a separate one and the caller merges; the alternative
+     * (one query on `paymentStatus`, filtered in memory) would scan every paid
+     * order ever placed.
+     *
+     * Unbounded `.limit(2000)`: a quarter's orders at this volume is a few
+     * hundred, and an export that silently truncated would understate a tax
+     * return. If this ever saturates, the fix is pagination with an explicit
+     * "more rows exist" signal in the CSV — never a higher cap.
+     */
+    async listInvoicedBetween(from, to) {
+        const [invoiced, paidUnnumbered] = await Promise.all([
+            this.db
+                .collection(this.collection)
+                .where("invoiceIssuedAt", ">=", from)
+                .where("invoiceIssuedAt", "<=", to)
+                .limit(2000)
+                .get(),
+            /*
+             * The exceptions. Bounded on `orderDate` because an un-invoiced order
+             * has no invoice date to window on — which is the whole problem with it
+             * — and because `paymentStatus == paid` alone would match every paid
+             * order in the collection's history.
+             */
+            this.db
+                .collection(this.collection)
+                .where(ORDER_FIELDS.PAYMENT_STATUS, "==", "paid")
+                .where(ORDER_FIELDS.ORDER_DATE, ">=", from)
+                .where(ORDER_FIELDS.ORDER_DATE, "<=", to)
+                .limit(2000)
+                .get(),
+        ]);
+        const byId = new Map();
+        for (const d of invoiced.docs) {
+            byId.set(d.id, { id: d.id, ...d.data() });
+        }
+        for (const d of paidUnnumbered.docs) {
+            const data = { id: d.id, ...d.data() };
+            // Only the genuinely un-numbered ones — a paid, numbered order is
+            // already in the first set, and adding it again would double every one
+            // of its rows in the return.
+            if (!data.invoiceNumber && !byId.has(d.id))
+                byId.set(d.id, data);
+        }
+        return [...byId.values()];
+    }
     async getExpiredPaymentDeadlines() {
         const snap = await this.db
             .collection(this.collection)
@@ -1056,6 +1164,27 @@ class OrderRepository extends BaseRepository {
              * early. Withholding is recoverable — the next sweep picks it up;
              * releasing early is not, because the money has gone.
              */
+            /*
+             * 🛑 A BUYER'S OWN CONFIRMATION RELEASES THE PAYOUT IMMEDIATELY.
+             *
+             * The owner's rule: an order is CONFIRMED when it is delivered and
+             * either the buyer says they received it, or 7 days pass. This filter
+             * only ever implemented the second half — `deliveryDate <= cutoff` —
+             * so a buyer who pressed "Mark complete" on day one still made their
+             * seller wait out the full hold. The fast path existed and bought the
+             * seller nothing.
+             *
+             * Safe in the direction that matters, and not by luck:
+             * `markOrderCompleteAction` is the only writer of `completedAt`, and it
+             * REFUSES while a return in any state, a posted refund or a buyer
+             * dispute is live — the same precondition the `order-complete`
+             * obligation carries. So honouring it here cannot release money while
+             * an issue is open; the hold is skipped only because the one party the
+             * hold protects has said they are satisfied.
+             */
+            const completedAt = toDateOrNull(o.data.completedAt);
+            if (completedAt)
+                return true;
             const anchor = toDateOrNull(o.data.deliveryDate) ?? toDateOrNull(o.data.updatedAt);
             if (!o.data.deliveryDate)
                 missingAnchor++;
@@ -1162,6 +1291,22 @@ OrderRepository.SELLER_SIEVE_FIELDS = {
     orderDate: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     contestable: { canFilter: true, canSort: false },
+    /*
+     * Lane segregation on the SELLER's order list — the same provenance axis
+     * `/user/orders` has had.
+     *
+     * 🛑 It was absent, and absence here is SILENT: `sieve.ts` sets
+     * `throwExceptions: false`, so an unallowlisted field does not raise —
+     * `findField` returns undefined and the clause is simply dropped. A lane
+     * chip emitting `orderType==auction` would therefore have returned the
+     * seller's ENTIRE order list while looking exactly like a working filter
+     * (Root Cause #62). Checked before wiring the chip, not after.
+     *
+     * 🛑 Never pushed as `orderType==standard`, for the same reason the admin
+     * set above carries that note: orders written before the field existed have
+     * no value to match. `/api/store/orders` refines that one case in memory.
+     */
+    orderType: { canFilter: true, canSort: false },
     // Fulfilment flags. Filterable so "which of my orders need gift wrap?" is a
     // query against the orders themselves — the whole point of recording the
     // add-on on the order rather than keeping a side list of who asked for what.

package/dist/features/orders/schemas/firestore.d.ts

@@ -7,6 +7,7 @@ import type { BaseDocument } from "../../../_internal/shared/types/base-document
 import type { ListingType } from "../../products/types";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
 import type { ReturnReason } from "../../../_internal/shared/features/orders/return-reasons";
+import type { DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
 import type { ReturnCustodyState } from "../../../_internal/shared/features/returns/custody";
 import type { ActualShipmentCost, SelectedShippingQuote, ShippingReconciliation } from "../../../_internal/shared/shipping/quote";
 import type { Encrypted, Plaintext } from "../../../security/encrypted";
@@ -352,6 +353,25 @@ export interface OrderRefundEvent {
     proofDocumentMimeType?: string;
     /** Required for Razorpay-override path ("failed auto-refund, settled manually"). */
     overrideReason?: string;
+    /**
+     * The credit note that documents this refund, e.g. `LIRCN/26-27/0001`
+     * (Phase 7, D12).
+     *
+     * 🛑 Per REFUND EVENT, not per order — an order can legitimately be refunded
+     * several times, and each reversal of tax needs its own numbered document
+     * referencing the original invoice. That is why the allocation claim for a
+     * credit note is keyed `${orderId}_${refundId}` while an invoice's is keyed
+     * on the order alone: keying a credit note on the order would refuse the
+     * second one.
+     *
+     * Only ever set on a refund that actually SETTLED. A `reserved` entry that
+     * failed is not a reversal of anything, and numbering it would leave a
+     * credit note in the series for money that never moved.
+     */
+    creditNoteNumber?: string;
+    creditNoteIssuedAt?: Date;
+    /** Private storage path — same no-public-URL rule as `invoiceStoragePath`. */
+    creditNoteStoragePath?: string;
 }
 /** One applied discount/coupon saved on the order for accounting and display */
 export interface AppliedOrderDiscount {
@@ -426,6 +446,21 @@ export interface OrderDocument extends BaseDocument {
      */
     acceptedAt?: Date;
     shippingDate?: Date;
+    /**
+     * The COURIER's estimated delivery date, captured at dispatch.
+     *
+     * 🛑 Not to be confused with `OrderSourcePreOrder.expectedDeliveryDate`,
+     * which is when a pre-ordered product RELEASES — a different concept that
+     * this field was mistaken for while planning the dispute gates.
+     *
+     * Optional, and will stay mostly empty for now: nothing platform-books yet
+     * (`createShipment` has zero callers), and a self-shipping seller types a
+     * tracking number with no estimate attached. `resolveDisputeEtd` therefore
+     * falls back to `shippingDate + DISPUTE_TRANSIT_WINDOW_DAYS` — without that
+     * fallback the `not_reached` dispute gate would be unreachable for every
+     * parcel currently shipped.
+     */
+    estimatedDeliveryDate?: Date;
     deliveryDate?: Date;
     /**
      * When the order was marked COMPLETE — the fact that awards points and
@@ -481,6 +516,37 @@ export interface OrderDocument extends BaseDocument {
      * figure the order may since have changed.
      */
     pointsAwarded?: number;
+    /**
+     * Points SPENT on this order as part-payment, in points (1 point = ₹1).
+     *
+     * 🛑 Distinct from `pointsAwarded` directly above, which is what the buyer
+     * EARNED. Both can be non-zero on one order — a buyer can pay partly with
+     * points and still earn on the goods value — and conflating them would make
+     * the ledger unexplainable in exactly the place it matters most.
+     *
+     * Written at order creation from `resolvePointsTender`, never from a request
+     * body. The ledger's `redemption` entry is keyed on this order, so this field
+     * and that entry must agree; the order carries it so a payout deduction and a
+     * refund can both answer "how much of this was points" without re-deriving a
+     * percentage of a total that may since have changed.
+     */
+    pointsApplied?: number;
+    /**
+     * What the buyer actually pays: `totalPrice − pointsApplied`.
+     *
+     * ## 🛑 THE FIGURE THE GATEWAY CAPTURES, and the one the guard compares
+     *
+     * `totalPrice` stays the full value of the order — that is what the invoice
+     * declares and what GST is computed against, because points are a DISCOUNT
+     * and not a reduction in the value of the supply (decision 5). `amountDue` is
+     * the cash leg.
+     *
+     * Absent means "nothing was tendered", so every order written before this
+     * existed reads correctly as `amountDue === totalPrice`. 🛑 Readers must use
+     * `amountDue ?? totalPrice` rather than defaulting to 0 — treating absence as
+     * zero would say every historical order was fully paid in points.
+     */
+    amountDue?: number;
     cancellationDate?: Date;
     cancellationReason?: string;
     /**
@@ -668,6 +734,25 @@ export interface OrderDocument extends BaseDocument {
         igst: number;
         gstAmount: number;
     }>;
+    /**
+     * The buyer's state — the PLACE OF SUPPLY (Phase 7).
+     *
+     * 🛑 This is the input the CGST/SGST-vs-IGST decision was made FROM, and it
+     * was not recorded anywhere. `isIntraStateSupply(buyerState, storeState)`
+     * runs at checkout and only its *result* survived, in the shape of which tax
+     * fields got populated — so an order could not state why it split the way it
+     * did, and GSTR-1 has a mandatory place-of-supply column that nothing could
+     * fill.
+     *
+     * `shippingAddress` is a flat STRING on this document and contains the state
+     * somewhere inside it; parsing a state back out of free text to file a tax
+     * return is not a thing to do. The value is in scope at order creation, so
+     * it is written there.
+     *
+     * Absent on orders placed before this, which the export reports rather than
+     * silently blanks.
+     */
+    placeOfSupply?: string;
     /**
      * OUR GST registration as it stood at the moment of supply — LetItRip is the
      * seller of record and invoices under its own GSTIN.
@@ -689,6 +774,58 @@ export interface OrderDocument extends BaseDocument {
     supplierGstin?: string;
     supplierLegalName?: string;
     supplierAddress?: string;
+    /**
+     * The invoice number from the gapless FY series, e.g. `LIR/26-27/0001`.
+     *
+     * 🛑 Allocated on `paymentStatus → paid`, never at order creation — a number
+     * burned on an abandoned COD order is a gap nobody can explain. Written once
+     * and never rewritten: a GST invoice is issued once, and an adjustment is a
+     * CREDIT NOTE, not a re-issue.
+     *
+     * Absence means "not yet invoiced", which is the correct state for a pending
+     * order and for every order placed before this phase.
+     */
+    invoiceNumber?: string;
+    /** When the number was allocated — the invoice's own date. */
+    invoiceIssuedAt?: Date;
+    /**
+     * Where the rendered PDF lives.
+     *
+     * 🛑 **`private/invoices/{orderId}/{uuid}.pdf`, with NO `mediaAssets` row and
+     * a RANDOM object name.** An invoice carries the buyer's full name, address
+     * and phone. `/api/media/[...slug]` applies **no authentication** over a
+     * bucket whose storage rule is `allow read: if true`, and the slug resolves
+     * through `mediaAssets` — so no row means no public URL exists at all.
+     *
+     * The random name is deliberately AGAINST the content-derived SEO-slug
+     * convention used everywhere else in this codebase, because guessable is the
+     * one property this must not have. `generateInvoiceFilename` is
+     * content-derived and is therefore the wrong tool here. Same reasoning as the
+     * digital-content decision (D103).
+     */
+    invoiceStoragePath?: string;
+    /**
+     * The arrangement's fees, SNAPSHOTTED at checkout.
+     *
+     * 🛑 Snapshotted, not re-read. A coordinator commits against a quoted total;
+     * if the rates were read again at settle a seller could raise them
+     * afterwards and the coordinator would absorb it. The precedent is exact —
+     * the refund path reads `finalSale` from this document rather than the live
+     * product, "because re-reading the live product would let a seller flip the
+     * switch afterwards" — and D61 generalises it to every agreement with a gap
+     * between terms-agreed and money-taken.
+     *
+     * Absent on every ordinary single-destination order, which is almost all of
+     * them.
+     */
+    sharedPurchase?: {
+        /** Distinct destinations, including the first. Always ≥ 2 when present. */
+        destinationCount: number;
+        /** Flat per-arrangement fee, as charged. */
+        handlingFee: number;
+        /** Extra shipping for destinations beyond the first, as charged. */
+        extraShippingFee: number;
+    };
     emiEnabled?: boolean;
     /** Number of monthly installments the buyer chose (2–6). */
     emiTenureMonths?: number;
@@ -776,6 +913,38 @@ export interface OrderDocument extends BaseDocument {
      * requires evidence and approval before anything is paid.
      */
     platformBookedShipment?: boolean;
+    /**
+     * We tried to book a courier for this order and could not.
+     *
+     * ## 🛑 ITS WHOLE PURPOSE IS TO STOP AN AUTO-CANCELLATION
+     *
+     * `seller-dispatch` is an `onDue: "act"` obligation on a 2-business-day
+     * clock. Without this field, an order sitting on OUR empty courier wallet is
+     * auto-cancelled and the buyer refunded — with the seller recorded as having
+     * failed to dispatch. The buyer paid, the seller did nothing wrong, and the
+     * platform's own funding state caused the cancellation.
+     *
+     * So every `onDue: "act"` policy anchored at or after dispatch gates its
+     * `precondition` on `!hasOpenCourierBlock(order)`. The obligation engine
+     * re-evaluates `precondition` at fire time and closes `superseded` when it
+     * returns false, so the clock pauses and resumes with no new mechanism.
+     *
+     * Absent means no block — which is every order ever written, so this needs
+     * no migration and changes nothing until something sets it.
+     *
+     * `reason` is the operator's word, not the seller's: the seller is told only
+     * that we could not book a courier right now, because our balance is our
+     * problem and not theirs.
+     */
+    courierBlock?: {
+        reason: "insufficient_funds" | "provider_error" | "unserviceable";
+        at: Date;
+        lastAttemptAt?: Date;
+        /** Attempts so far, so the digest can distinguish stuck from transient. */
+        attempts: number;
+        /** Upstream detail, for the admin surface only. Never shown to a seller. */
+        detail?: string;
+    };
     /**
      * The self-shipped reimbursement workflow: evidence in, approved amount out.
      *
@@ -970,11 +1139,37 @@ export interface OrderDocument extends BaseDocument {
     /** True when `paymentReviewAutoApprove` approved this order after 2 hours of no manual admin review. */
     autoApproved?: boolean;
     autoApprovedAt?: Date;
-    /** Buyer/seller/admin dispute raised against an auto-approved order — surfaces to the admin queue, does not itself reverse payment/order status. */
+    /**
+     * A buyer/seller/admin dispute. Surfaces to the admin queue; does not itself
+     * reverse payment or order status.
+     *
+     * 🛑 This used to say "against an auto-approved order", and that was the
+     * whole scope: `raiseOrderDisputeAction` refused anything else, telling the
+     * caller to use the return/refund flow. Disputes are now GENERAL — any
+     * delivered-or-late order can be disputed, gated by `disputeKind`.
+     */
     disputeRaised?: boolean;
     disputeRaisedBy?: string;
     disputeRaisedAt?: Date;
+    /**
+     * The reason's LABEL, snapshotted at the moment the dispute was raised.
+     *
+     * 🛑 A snapshot, not a lookup, and that is the point: `disputeReasons` rows
+     * can be retired or reworded by staff, and neither may rewrite what a buyer
+     * said months ago. `disputeReasonId` below is the join key for analytics;
+     * THIS is the record.
+     *
+     * Still a plain `string` and still the field every existing surface renders,
+     * so pre-2026-10-22 disputes (free text typed by the buyer) keep displaying
+     * unchanged rather than being orphaned beside a new field.
+     */
     disputeReason?: string;
+    /** Which gate this dispute passed. Absent on pre-2026-10-22 disputes. */
+    disputeKind?: DisputeKind;
+    /** `disputeReasons/{id}`. The join key for "what are buyers reporting". */
+    disputeReasonId?: string;
+    /** The buyer's own words. Free text, never parsed, never gated on. */
+    disputeDetail?: string;
     disputeStatus?: "open" | "resolved";
     /**
      * Same-shape payment record regardless of how the buyer paid — manual