@mohasinac/appkit 4.58.0 → 4.60.0

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

@@ -1,14 +1,40 @@
 import { buildOrderSearchTxt } from "../../../utils/search-txt-builders.js";
 import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../utils/search-txt-query.js";
 import { normalizeError } from "../../../errors/normalize.js";
-import { DatabaseError, NotFoundError } from "../../../errors/index.js";
+/*
+ * `ValidationError` from `../../../errors`, which is the REAL one — the class
+ * `mapToHttpError` instanceof-checks to produce a 400. The other
+ * `ValidationError` (in `_internal/shared/errors`) is a structurally
+ * unrelated class that falls through to a generic 500; Root Cause #53 records
+ * that mix-up swallowing ~100 call sites' validation messages.
+ */
+import { DatabaseError, NotFoundError, ValidationError } from "../../../errors/index.js";
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
 import { maskPii, revealPii, ORDER_PII_FIELDS, } from "../../../security/index.js";
 import { serverTimestamp, arrayUnion } from "../../../contracts/field-ops.js";
 import { createOrderId, ORDER_COLLECTION, ORDER_TRACKED_FIELDS, OrderStatusValues, } from "../schemas/index.js";
 import { withHistory } from "../../../_internal/shared/history/index.js";
 import { MANUAL_PAYMENT_METHODS, PAYMENT_REVIEW_QUEUE_SCAN_LIMIT, } from "../constants/payment-window.js";
+import { isLegalOrderTransition, describeIllegalTransition, } from "../constants/transitions.js";
+import { reconcileObligations } from "../../../_internal/shared/obligations/deadlines.js";
+import { obligationsRepository } from "../../obligations/repository/obligations.repository.js";
 import { ORDER_FIELDS } from "../../../constants/field-names.js";
+/**
+ * An illegal status transition was refused.
+ *
+ * Its own class so the webhook ingest can distinguish "this event is LATE"
+ * from "this event is broken": a replayed `order.paid` arriving after the order
+ * shipped is not wrong, it is out of date, and the correct ack is 200 with a
+ * `status: "conflict"` row rather than a 500 asking the gateway to retry a
+ * regression it can never win.
+ */
+export class OrderStatusError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = "ORDER_STATUS_TRANSITION_INVALID";
+        this.name = "OrderStatusError";
+    }
+}
 /**
  * Statuses that count toward a user's per-product / per-bundle purchase
  * allowance (SB6 maxPerUser enforcement). Cancelled and refunded orders are
@@ -21,6 +47,101 @@ const ACTIVE_ALLOWANCE_STATUSES = [
     ORDER_FIELDS.STATUS_VALUES.SHIPPED,
     ORDER_FIELDS.STATUS_VALUES.DELIVERED,
 ];
+/**
+ * Status → the timestamp field recording when the order ENTERED that status.
+ *
+ * 🛑 `deliveryDate` had NO WRITER anywhere in the live application until
+ * 2026-10-21 — only seed data and display components referenced it — and that
+ * single omission unanchored every post-delivery deadline in the product:
+ *
+ *   · `assertReturnWindowOpen` fell through to an `updatedAt` fallback, so the
+ *     return window was measured from the order's LAST MUTATION. Any write at
+ *     all — a note, `assignWorker`, a `statusHistory` append — silently
+ *     restarted the buyer's clock.
+ *   · `PROTECTION_CLAIM_WINDOW_HOURS` had nothing to measure from, so the
+ *     shipment- and sale-protection claim windows (which we charge 2% and 3%
+ *     for) could not open or close.
+ *   · The payout hold had no anchor, which is half of why three payout paths
+ *     honour one intended hold between them (D25).
+ *
+ * A FACT, never a deadline. The deadline is derived from it on read, so a
+ * policy change re-dates nothing and there is no stored mirror to drift
+ * (Root Cause #42).
+ *
+ * 🛑 `cancellationDate` is deliberately ABSENT from this map even though the
+ * field exists. `cancelOrder` already sets it in the same patch, and stamping
+ * it here too would be a second writer for one fact — the exact shape the rest
+ * of this comment is about. Add a status here only when nothing else owns its
+ * anchor.
+ */
+const STATUS_ANCHOR_FIELD = {
+    [ORDER_FIELDS.STATUS_VALUES.SHIPPED]: "shippingDate",
+    [ORDER_FIELDS.STATUS_VALUES.DELIVERED]: "deliveryDate",
+};
+/**
+ * Stamp the anchor for a status this patch is moving INTO.
+ *
+ * Three properties, each load-bearing:
+ *
+ * 1. **Only on a real transition.** Gated on `current?.status !== patch.status`,
+ *    so re-writing `delivered` over `delivered` (a tracking-number edit, a
+ *    replayed webhook) does not move the anchor. Without that gate every
+ *    subsequent write would push the return window further out — which is the
+ *    `updatedAt` bug this exists to remove, reintroduced by the fix for it.
+ * 2. **Never overwrites an explicit value.** A caller passing its own
+ *    `deliveryDate` — a backfill, an admin correcting a date, a courier
+ *    webhook reporting when delivery actually happened — wins. We are
+ *    supplying a default, not asserting authority.
+ * 3. **Costs no reads.** `updateWithHistory` already holds `current`, which is
+ *    why this belongs there and not in a service layer (Rule #6).
+ */
+/**
+ * Coerce whatever Firestore actually handed us into a `Date`, or `null`.
+ *
+ * 🛑 FOUR shapes reach this, and the type annotations claim only one.
+ * `OrderDocument` declares these fields `Date`, but the queries below read
+ * `d.data()` RAW — no `mapDoc`, because they need the `DocumentReference` for
+ * a later batch write — so what arrives is:
+ *
+ *   · a Firestore `Timestamp` (the normal case, exposing `.toDate()`)
+ *   · a real `Date` (when a doc was just written in-process)
+ *   · a **string** — `/api/store/orders/[id]` wrote `shippingDate` as
+ *     `new Date().toISOString()` until 2026-10-21 while the sibling
+ *     `customShipOrder` wrote a `Date`, so live documents carry both
+ *   · a number (epoch ms), from any hand-written fixture
+ *
+ * A bare `o.data.deliveryDate.getTime()` therefore throws on the common case
+ * (a Timestamp has no `getTime`), and `new Date(timestamp)` yields an Invalid
+ * Date rather than failing — which would silently compare as `false` and
+ * withhold the payout forever with no error. Mirrors the four-shape handling
+ * in `orders/adapters.ts:27`, returning a `Date` rather than an ISO string.
+ */
+function toDateOrNull(value) {
+    if (!value)
+        return null;
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (typeof value === "object" && typeof value.toDate === "function") {
+        const d = value.toDate();
+        return d instanceof Date && !Number.isNaN(d.getTime()) ? d : null;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    return null;
+}
+function stampStatusAnchor(current, patch) {
+    const nextStatus = patch.status;
+    if (!nextStatus || current?.status === nextStatus)
+        return patch;
+    const field = STATUS_ANCHOR_FIELD[nextStatus];
+    if (!field)
+        return patch;
+    if (patch[field] !== undefined)
+        return patch;
+    return { ...patch, [field]: new Date() };
+}
 class OrderRepository extends BaseRepository {
     constructor() {
         super(ORDER_COLLECTION);
@@ -130,6 +251,52 @@ class OrderRepository extends BaseRepository {
      */
     known) {
         const current = known !== undefined ? known : await this.findById(orderId);
+        /*
+         * ── THE STATUS TRANSITION GUARD ───────────────────────────────────────────
+         *
+         * 🛑 ENFORCED HERE, and the location is the whole reason this is cheap.
+         *
+         * `updateWithHistory` is the single choke point all seven write primitives
+         * route through, AND it is the only place that already holds the current
+         * document — so the guard costs **zero extra Firestore reads**. Enforcing
+         * at the service layer instead would be four call-site edits and would
+         * still miss `settleRefund`'s own write, which goes straight through here.
+         *
+         * What it stops, from the census in `constants/transitions.ts`: two of
+         * `updateStatus`'s four callers pass an arbitrary status from a REQUEST
+         * BODY with `as any`, so a seller could set `delivered` on an unpaid order
+         * or regress `delivered` → `pending`, and nothing refused it. A replayed
+         * `order.paid` webhook could do the same.
+         *
+         * 🛑 It is skipped when `current` is null — a brand-new document has no
+         * `from` state, and refusing the first write would make the guard reject
+         * order creation. Also skipped when the patch carries no `status`, which
+         * is most writes (a tracking number, a note, a payout flag).
+         */
+        const nextStatus = patch.status;
+        if (current?.status && nextStatus && !isLegalOrderTransition(current.status, nextStatus)) {
+            if (ctx?.allowStatusOverride) {
+                /*
+                 * The admin escape hatch — RECORDED, never silent. An override that
+                 * leaves no trace is indistinguishable from the bug this guard exists
+                 * to catch, so it goes into `statusHistory` as an explicit note and the
+                 * write proceeds.
+                 */
+                ctx = {
+                    ...ctx,
+                    note: [
+                        ctx.note,
+                        `status override: ${current.status} → ${nextStatus} is not a legal transition`,
+                    ]
+                        .filter(Boolean)
+                        .join(" · "),
+                };
+            }
+            else {
+                throw new OrderStatusError(describeIllegalTransition(current.status, nextStatus));
+            }
+        }
+        patch = stampStatusAnchor(current, patch);
         const withEntry = withHistory(current, patch, {
             tracked: ORDER_TRACKED_FIELDS,
             actor: ctx?.actor ?? { role: "system" },
@@ -148,7 +315,72 @@ class OrderRepository extends BaseRepository {
         // `null` means no tracked field actually changed — write the patch as-is
         // so an untracked update never grows the array.
         // Plain: this is a write payload and `update` encrypts.
-        return this.update(orderId, (withEntry ?? patch));
+        const written = await this.update(orderId, (withEntry ?? patch));
+        /*
+         * ── OBLIGATION RECONCILIATION (Phase 5b) ──────────────────────────────────
+         *
+         * Reconciled from the order's OWN write, here, for two reasons.
+         *
+         * 🛑 NOT a Firestore trigger. An `onOrderWrite` trigger that wrote
+         * `obligations`, whose sweep then wrote `orders`, is Root Cause #92's
+         * self-write loop exactly — 1,017,548 invocations in 24 hours against a
+         * 2M/month quota, plus a correctly-guarded sibling woken a million times
+         * just to return. A correct guard does not save you from a neighbour's
+         * loop.
+         *
+         * 🛑 And it costs ZERO extra reads: the post-write document is assembled
+         * from `current` plus `patch` rather than re-read. `reconcileObligations`
+         * is a pure function over that shape.
+         *
+         * Fire-and-forget, and that is deliberate: an obligation is a derived HINT.
+         * Letting its write fail the ORDER write — the one the caller is waiting on,
+         * which may be a payment confirmation — would trade a real transaction for
+         * a bookkeeping row. The next write reconciles again, and the sweep's
+         * re-read of the subject is what makes a missed row self-correcting.
+         */
+        void this.reconcileObligationsFor({ ...(current ?? {}), ...patch, id: orderId }, current).catch((err) => {
+            void normalizeError(err);
+        });
+        return written;
+    }
+    /**
+     * Open/close this order's obligations to match what its own facts imply.
+     *
+     * Public so the obligation sweep can re-run it after acting, and so a
+     * backfill can reconcile existing orders without a synthetic write.
+     */
+    async reconcileObligationsFor(order, 
+    /**
+     * The pre-write document, so the close set is `was-open MINUS is-open`
+     * rather than every kind that is not open. Omit ONLY for a deliberate
+     * backfill — see `reconcileObligations`' own 🛑 on the cost.
+     */
+    previous) {
+        const { open, close } = reconcileObligations(order, previous);
+        const repo = obligationsRepository();
+        for (const deadline of open) {
+            await repo.open({
+                kind: deadline.kind,
+                subjectCollection: ORDER_COLLECTION,
+                subjectId: order.id,
+                dueAt: deadline.dueAt,
+                ...(order.isTestData ? { isTestData: true } : {}),
+                note: deadline.policy.describe,
+            });
+        }
+        /*
+         * Closed as `met`, not `superseded`: reaching here means the order's own
+         * facts no longer satisfy the precondition, i.e. the thing the obligation
+         * was waiting for HAPPENED. `superseded` is reserved for the sweep finding
+         * a stale row at fire time, which is a different story and worth
+         * distinguishing in the record.
+         */
+        for (const kind of close) {
+            await repo.close(order.id, kind, {
+                state: "met",
+                closeReason: "the order's own state no longer requires it",
+            });
+        }
     }
     async updateStatus(orderId, status, additionalData, ctx) {
         return this.updateWithHistory(orderId, { status, ...additionalData, updatedAt: new Date() }, ctx, "orderRepository.updateStatus");
@@ -404,6 +636,162 @@ class OrderRepository extends BaseRepository {
      * Append one refund event to the order and mark it non-contestable.
      * If `becomeRefunded` is true, also transitions the order status to "refunded".
      */
+    /**
+     * PHASE A — reserve a refund slot atomically, enforcing the cumulative cap.
+     *
+     * 🛑 WHY A TRANSACTION, AND WHY NOT `arrayUnion` (D1 + D6).
+     *
+     * `postRefundEvent` below does `findById` then `[...existing, event]` — a
+     * read-then-write. Two concurrent refunds both read the same `existing` and
+     * the second write **overwrites the first's append, losing an event
+     * entirely**. And the cap check lived in the ACTION, outside any
+     * transaction, so it was TOCTOU: two requests could each see a clear cap and
+     * both proceed. Combined with the cap comparing against `totalPrice` rather
+     * than the remaining balance (D1), ₹500 and another ₹500 both passed on a
+     * ₹600 order — **two real gateway refunds, both successful.**
+     *
+     * `arrayUnion` is the obvious fix and is WRONG here on three counts: it
+     * cannot evaluate the cumulative cap (the whole point), it cannot build the
+     * `withHistory` entry, and it dedupes by DEEP EQUALITY — so two legitimate
+     * identical ₹100 partial refunds would silently merge into one.
+     *
+     * The entry lands with `status: "reserved"`, which `committedRefundTotal`
+     * counts. That is what makes the reservation real: a concurrent request sees
+     * the pending amount and cannot refund against a balance already spoken for.
+     * A later `failed` settlement releases it simply by being skipped.
+     *
+     * Throws rather than returning a flag — a caller that ignores a boolean here
+     * calls the gateway anyway, which is the failure this prevents.
+     */
+    async reserveRefund(orderId, event, 
+    /** Resolved by the caller from `refundCapacity`; see `refundable-base.ts`. */
+    opts) {
+        const docRef = this.getCollection().doc(orderId);
+        await this.db.runTransaction(async (tx) => {
+            const snap = (await tx.get(docRef));
+            const data = typeof snap?.data === "function" ? snap.data() : undefined;
+            if (!data)
+                throw new NotFoundError(`Order ${orderId} not found`);
+            const existing = (data.refunds ?? []);
+            /*
+             * Idempotency inside the transaction too, not only at the claim doc.
+             * The claim is the at-most-once gate for a RETRY of the same request;
+             * this catches the case where a reservation landed but the claim write
+             * did not, and makes re-entry a no-op rather than a second slot.
+             */
+            if (existing.some((r) => r.refundId === event.refundId))
+                return;
+            const committed = existing
+                .filter((r) => r.status !== "failed")
+                .reduce((sum, r) => sum + (r.amount ?? 0), 0);
+            /*
+             * The cap, evaluated HERE rather than by the caller — inside the
+             * transaction is the only place it is not a race.
+             */
+            if (committed + event.amount > opts.refundableBase + opts.epsilon) {
+                const remaining = Math.max(0, opts.refundableBase - committed);
+                throw new ValidationError(`Refund of ₹${event.amount.toFixed(2)} exceeds the ₹${remaining.toFixed(2)} still refundable on this order.`);
+            }
+            tx.update(docRef, {
+                refunds: [...existing, { ...event, status: "reserved" }],
+                contestable: false,
+                updatedAt: new Date(),
+            });
+        });
+    }
+    /**
+     * PHASE B — settle a reserved refund: `processed` with the gateway's id, or
+     * `failed`, which releases the reservation.
+     *
+     * Runs AFTER the provider call, which must sit outside any transaction: a
+     * Firestore transaction retries its body, and a retried network call is a
+     * second refund. This is the only ordering in which "money left the gateway
+     * and we have no record of it" is impossible — a crash between the provider
+     * call and this write leaves a `reserved` entry and an unsettled claim,
+     * which is exactly the shape Phase 4's reconciler looks for.
+     *
+     * Goes through `updateWithHistory`, so the TIMELINE entry is written at
+     * settlement rather than at reservation. That is deliberate: the history
+     * should record money that moved, not an intent that may yet fail.
+     */
+    async settleRefund(orderId, refundId, outcome, becomeRefunded = false, ctx) {
+        const order = await this.findById(orderId);
+        if (!order)
+            throw new NotFoundError(`Order ${orderId} not found`);
+        const existing = order.refunds ?? [];
+        const target = existing.find((r) => r.refundId === refundId);
+        if (!target)
+            throw new NotFoundError(`Reserved refund ${refundId} not found on order ${orderId}`);
+        const settled = existing.map((r) => r.refundId === refundId
+            ? {
+                ...r,
+                ...outcome,
+                ...(outcome.status === "processed" ? (outcome.providerFields ?? {}) : {}),
+            }
+            : r);
+        return this.updateWithHistory(orderId, {
+            refunds: settled,
+            /*
+             * `becomeRefunded` only on a SUCCESSFUL settlement. Marking an order
+             * refunded on a failed gateway call would be the worst possible lie:
+             * terminal status, no money moved.
+             */
+            ...(becomeRefunded && outcome.status === "processed"
+                ? {
+                    status: "refunded",
+                    /*
+                     * 🛑 Clears the INTENT that `cancelOrder` wrote.
+                     *
+                     * `cancelOrder(…, refundAmount)` sets `refundStatus: "pending"`,
+                     * and until 2026-10-21 nothing anywhere ever wrote a terminal
+                     * value — so a successfully refunded cancellation kept reading
+                     * `"pending"` forever. That is not cosmetic: D14's detector looks
+                     * for cancelled orders that still owe money, and a flag stuck at
+                     * `"pending"` would make every *successful* refund look like a
+                     * failure.
+                     *
+                     * It also gives `issuePartialRefund`'s
+                     * `refundStatus === COMPLETED` guard its first writer. That check
+                     * has existed for a long time and could never fire, so a
+                     * fully-refunded order could be submitted for another full refund
+                     * and was stopped only by the cumulative cap one layer down.
+                     *
+                     * Only on `processed` + `isFull`, because those are the two facts
+                     * that make "completed" true. A failed settlement deliberately
+                     * leaves `"pending"` standing — that is the state the detector
+                     * must still see.
+                     */
+                    refundStatus: "completed",
+                }
+                : {}),
+            updatedAt: new Date(),
+        }, {
+            ...ctx,
+            extraChanges: {
+                refund: {
+                    from: null,
+                    to: {
+                        refundId,
+                        type: target.type,
+                        amount: target.amount,
+                        reason: target.reason,
+                        outcome: outcome.status,
+                    },
+                },
+            },
+            actor: ctx?.actor ?? { uid: target.refundedBy, role: "admin" },
+            reason: ctx?.reason ?? target.reason,
+        }, "orderRepository.settleRefund", order);
+    }
+    /**
+     * 🛑 LEGACY — prefer `reserveRefund` + `settleRefund`.
+     *
+     * Kept because several non-gateway paths (manual refunds with no provider
+     * call, and the out-of-stock auto-refund) post a single terminal event with
+     * nothing to reserve against. Its read-then-write append is still a lost-
+     * update risk under concurrency (D6); do not route a new gateway refund
+     * through it.
+     */
     async postRefundEvent(orderId, event, becomeRefunded = false, ctx) {
         const order = await this.findById(orderId);
         if (!order)
@@ -594,21 +982,23 @@ class OrderRepository extends BaseRepository {
      * once it's delivered (a seller-enabled `allowShipBeforeEmiComplete` item
      * can be delivered long before EMI collection finishes).
      */
-    async getEligibleForPayoutSweep() {
-        const snap = await this.db
-            .collection(this.collection)
-            .where(ORDER_FIELDS.PAYOUT_STATUS, "==", "eligible")
-            .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.DELIVERED)
-            .limit(500)
-            .get();
-        return snap.docs
-            .map((d) => ({
-            id: d.id,
-            ref: d.ref,
-            data: { id: d.id, ...d.data() },
-        }))
-            .filter((o) => !o.data.emiEnabled || o.data.emiComplete);
-    }
+    /*
+     * 🛑 `getEligibleForPayoutSweep()` was DELETED on 2026-10-21. Do not
+     * reinstate it.
+     *
+     * It filtered on `payoutStatus == "eligible" && status == "delivered"` and
+     * NOTHING ELSE — no time cutoff of any kind. `weeklyPayoutEligibility` (the
+     * Saturday job) called it, so the intended 7-day payout hold was not merely
+     * miscomputed, it was **unreachable as a floor**: the weekly sweep paid out
+     * an order delivered yesterday, every Saturday.
+     *
+     * Three payout paths existed and ONE hold was intended; it was honoured by
+     * zero of the three. The manual seller "Request payout"
+     * (`seller-actions.ts`) had no time check either. Collapsing to a single
+     * query is what makes the hold enforceable at all — a second entry point
+     * with its own predicate is how this happened, so the fix is one query, not
+     * a cutoff added to two.
+     */
     /**
      * Cloud Functions: find auto-payout eligible delivered orders older than windowDays business days.
      * @param windowDays - number of business days since delivery
@@ -616,21 +1006,74 @@ class OrderRepository extends BaseRepository {
      *
      * See {@link getEligibleForPayoutSweep} for the EMI-incomplete exclusion rationale.
      */
-    async getEligibleAutomatic(cutoff) {
+    async getEligibleAutomatic(cutoff, opts) {
+        /*
+         * 🛑 NO DATE INEQUALITY IN THE QUERY, and this is the load-bearing
+         * decision in the whole payout-hold fix. Both obvious shapes are wrong:
+         *
+         * (a) `.where(UPDATED_AT, "<=", cutoff)` — what this used to do (D29).
+         *     `updatedAt` is bumped by EVERY write, so a note, an `assignWorker`,
+         *     a `statusHistory` append or a tracking-number edit silently RESTARTS
+         *     the hold. The clock measured "time since anyone last touched this
+         *     order", not "time since delivery".
+         *
+         * (b) `.where(DELIVERY_DATE, "<=", cutoff)` — the obvious fix, and it
+         *     would pay out NOBODY, FOREVER, SILENTLY. A Firestore inequality
+         *     excludes every document that LACKS the field, and `deliveryDate`
+         *     had no writer at all until 2026-10-21 — so every order delivered
+         *     before today is missing it, the query returns zero rows, and
+         *     "no eligible orders" is indistinguishable from a working sweep with
+         *     nothing to do. That is Root Cause #100 exactly, which is the
+         *     incident where `orderBy("itemsSold")` returned 0 of 95 products and
+         *     the endpoint answered 200.
+         *
+         * So the query finds CANDIDATES on fields that certainly exist, bounded,
+         * and the anchor test is a per-row predicate below. One query, no new
+         * composite index, and no way to silently return nothing.
+         */
         const snap = await this.db
             .collection(this.collection)
             .where(ORDER_FIELDS.PAYOUT_STATUS, "==", "eligible")
             .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.DELIVERED)
-            .where(ORDER_FIELDS.UPDATED_AT, "<=", cutoff)
             .limit(500)
             .get();
-        return snap.docs
+        let missingAnchor = 0;
+        const rows = snap.docs
             .map((d) => ({
             id: d.id,
             ref: d.ref,
             data: { id: d.id, ...d.data() },
         }))
-            .filter((o) => !o.data.emiEnabled || o.data.emiComplete);
+            .filter((o) => !o.data.emiEnabled || o.data.emiComplete)
+            .filter((o) => {
+            /*
+             * The anchor, with a conservative fallback. `deliveryDate` is the
+             * truth; `updatedAt` is what every pre-2026-10-21 order has instead.
+             *
+             * Falling back is safe in the one direction that matters: `updatedAt`
+             * is always >= `deliveryDate` (any write bumps it), so the fallback can
+             * only ever WITHHOLD a payout longer than intended, never release one
+             * early. Withholding is recoverable — the next sweep picks it up;
+             * releasing early is not, because the money has gone.
+             */
+            const anchor = toDateOrNull(o.data.deliveryDate) ?? toDateOrNull(o.data.updatedAt);
+            if (!o.data.deliveryDate)
+                missingAnchor++;
+            if (!anchor)
+                return false;
+            return anchor.getTime() <= cutoff.getTime();
+        });
+        if (missingAnchor > 0) {
+            /*
+             * Visible, because the fallback is a transitional state and not the
+             * design. As orders delivered after 2026-10-21 flow through, this count
+             * should trend to zero; if it does not, something is still setting
+             * `delivered` by a path that bypasses `updateWithHistory`'s anchor
+             * stamp, and these sellers are being paid late for no stated reason.
+             */
+            opts?.onWarn?.(`${missingAnchor} delivered order(s) have no deliveryDate — the payout hold fell back to updatedAt, which withholds longer than intended`, { missingAnchor, candidates: snap.size });
+        }
+        return rows;
     }
     /**
      * Cloud Functions: EMI reminder sweep — orders on an active (not yet fully