@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/_internal/server/functions/scheduled.d.ts

@@ -9,12 +9,83 @@ export declare const productStatsSync: import("./types").ScheduledFunctionDefini
 export declare const revenueRollup: import("./types").ScheduledFunctionDefinition;
 export declare const searchIndexBuild: import("./types").ScheduledFunctionDefinition;
 export declare const priceIndexRollup: import("./types").ScheduledFunctionDefinition;
+export declare const marketPriceRollup: import("./types").ScheduledFunctionDefinition;
 export declare const analyticsAlertEvaluate: import("./types").ScheduledFunctionDefinition;
 export declare const pageViewRollup: import("./types").ScheduledFunctionDefinition;
 export declare const pageViewPrune: import("./types").ScheduledFunctionDefinition;
 export declare const dailyStatusDigest: import("./types").ScheduledFunctionDefinition;
 export declare const dailyDataCleanup: import("./types").ScheduledFunctionDefinition;
 export declare const countersReconcile: import("./types").ScheduledFunctionDefinition;
+/**
+ * Payment reconciliation — R2, R3 and R4. Daily 05:30 UTC.
+ *
+ * 🛑 ITS OWN FUNCTION, and the two obvious places to fold it are both wrong.
+ *
+ * `countersReconcile` above already runs at its 540 s ceiling, so adding work
+ * there is how a job starts timing out and taking category metrics with it.
+ * `autoPayoutEligibility` is tempting because both touch orders, but
+ * `priceIndexRollup`'s own comment sets the precedent: a job should be able to
+ * fail without taking an unrelated one down, and these two share nothing beyond
+ * the collection.
+ *
+ * Cloud Scheduler bills **per registered job** (3 free, 28 already registered),
+ * so this is ~$0.10/month — a cost the Firebase budget table explicitly accepts
+ * for a distinct cadence rather than contorting the schedule around it.
+ *
+ * 🛑 R1 is NOT here. It is folded into `paymentWindowTimeout` (every 5 minutes),
+ * because a webhook we received and lost should not wait up to 24 hours to be
+ * noticed — and its query is one indexed read, so the tight loop is free.
+ *
+ * 05:30 UTC = 11:00 IST, deliberately after `countersReconcile` (03:00) and
+ * `autoPayoutEligibility` so a payout decision is never taken on the same tick
+ * as the reconciliation that might open a case blocking it.
+ */
+/**
+ * Every deadline in the order lifecycle — one job, every 5 minutes.
+ *
+ * 🛑 ONE JOB FOR ~20 SCENARIOS, and the Scheduler count goes DOWN.
+ *
+ * The alternative was a cron per scenario, which is ~$2/month *and* `O(n²)`
+ * coverage reasoning — D25, D27 and the duplicate buyout notification are all
+ * that pattern failing. Here it is one indexed query per tick, empty when idle,
+ * and `obligations`' deterministic document id gives "at most one open
+ * obligation per (subject, kind)" so a double reconcile is a no-op.
+ *
+ * Phase 8 retires `paymentWindowTimeout`, `pendingOrderTimeout` and
+ * `paymentReviewAutoApprove` once their policy rows are proven, taking the
+ * registered count **28 → 29 → 27**.
+ *
+ * 🛑 NOT a Firestore trigger on `orders`. A trigger writing `obligations`
+ * whose sweep writes `orders` is Root Cause #92's self-write loop — the one
+ * that cost 1,017,548 invocations in 24 hours. Obligations are reconciled
+ * inside the order's own write, where the document is already in hand.
+ */
+export declare const obligationSweep: import("./types").ScheduledFunctionDefinition;
+export declare const paymentReconcile: import("./types").ScheduledFunctionDefinition;
+/**
+ * 🛑 ITS OWN FUNCTION, AND DELIBERATELY NOT A FIRESTORE TRIGGER.
+ *
+ * A trigger on `inventoryPlacements` writing back to `storageBoxes` would fire
+ * on every pick, move and receive — a 50-row receive is 50 placement writes and
+ * would wake it 50 times to recompute the same two boxes. It is also one
+ * refactor away from Root Cause #92's shape, which cost 1,017,548 invocations
+ * in 24 hours against a 2M/month free quota.
+ *
+ * Nightly is right because the rollup is ADVISORY: every surface that must be
+ * correct reads placements directly (the box detail page does, and says so),
+ * so a day-stale rollup costs a slightly wrong number in a list and never a
+ * wrong decision.
+ *
+ * 🛑 06:15 UTC, AND THE SLOT WAS CHOSEN BY COUNTING, NOT BY EYE. My first
+ * pick was 04:30 with a comment claiming it kept three collection-walking jobs
+ * out of the same minute — while `30 4 * * *` ALREADY held two
+ * (`priceIndexRollup` at 540s/512MiB among them), so it would have made three
+ * and the comment would have asserted the opposite of what it did.
+ *
+ * `grep -o 'cron: "…"' | sort | uniq -c` over this file is the check: 06:15 is
+ * empty, clear of the dense 00:00–05:30 band and of the 10:00 IST digest.
+ */
+export declare const boxRollupReconcile: import("./types").ScheduledFunctionDefinition;
 export declare const positionsReconcile: import("./types").ScheduledFunctionDefinition;
 export declare const cartPrune: import("./types").ScheduledFunctionDefinition;
 export declare const notificationPrune: import("./types").ScheduledFunctionDefinition;
@@ -28,4 +99,4 @@ export declare const prizeDrawExpiryReveal: import("./types").ScheduledFunctionD
 export declare const bundleStockSync: import("./types").ScheduledFunctionDefinition;
 export declare const emiInstallmentReminder: import("./types").ScheduledFunctionDefinition;
 export declare const catalogueImageStalenessReminder: import("./types").ScheduledFunctionDefinition;
-export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];
+export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];

package/dist/_internal/server/functions/scheduled.js

@@ -1,6 +1,6 @@
 // Scheduled function definitions (Cloud Scheduler triggers).
 // Cron syntax accepts both Firebase shorthand and standard cron expressions.
-import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, priceIndexRollupHandler, searchIndexBuildHandler, analyticsAlertEvaluateHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testDataCleanupHandler, } from "../jobs/handlers/index.js";
+import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, boxRollupReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, obligationSweepHandler, paymentReconcileHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, priceIndexRollupHandler, marketPriceRollupHandler, searchIndexBuildHandler, analyticsAlertEvaluateHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testDataCleanupHandler, } from "../jobs/handlers/index.js";
 import { defineFunction } from "./define.js";
 const REGION = "asia-south1";
 const EVERY_5_MIN = "every 5 minutes";
@@ -113,6 +113,28 @@ export const priceIndexRollup = defineFunction({
     handler: priceIndexRollupHandler,
     options: { region: REGION, timeoutSeconds: 540, memory: "512MiB", maxInstances: 1 },
 });
+/*
+ * The ASKING half of the same page, from dated `priceObservations` rows.
+ *
+ * 🛑 A separate function from `priceIndexRollup`, not a second pass inside it,
+ * and the reason is the one that file already states for itself: these two
+ * bands are *"rendered side by side and never averaged"*. Sharing a function
+ * would also share a failure — a bad observation import taking the realised-
+ * sale index down with it, when the two read entirely different collections and
+ * have no reason to fail together.
+ *
+ * 05:00 UTC, half an hour after the sold half: both feed one page, and running
+ * them adjacently means a reader never sees one half a day fresher than the
+ * other. Not simultaneously — `maxInstances: 1` on each, but they would still
+ * contend for the same Firestore read budget in the same minute for no gain.
+ */
+export const marketPriceRollup = defineFunction({
+    name: "marketPriceRollup",
+    description: "Roll up dated price observations into marketPriceIndex/{leafId} — mode, 6-month low/high (daily 05:00 UTC = 10:30 IST).",
+    trigger: { kind: "schedule", cron: "0 5 * * *", timeZone: "UTC" },
+    handler: marketPriceRollupHandler,
+    options: { region: REGION, timeoutSeconds: 540, memory: "512MiB", maxInstances: 1 },
+});
 /*
  * Evaluate the alert rules sellers and admins configured — hourly, 20 past.
  *
@@ -178,6 +200,94 @@ export const countersReconcile = defineFunction({
     handler: countersReconcileHandler,
     options: { region: REGION, timeoutSeconds: 540, memory: "256MiB", maxInstances: 1 },
 });
+/**
+ * Payment reconciliation — R2, R3 and R4. Daily 05:30 UTC.
+ *
+ * 🛑 ITS OWN FUNCTION, and the two obvious places to fold it are both wrong.
+ *
+ * `countersReconcile` above already runs at its 540 s ceiling, so adding work
+ * there is how a job starts timing out and taking category metrics with it.
+ * `autoPayoutEligibility` is tempting because both touch orders, but
+ * `priceIndexRollup`'s own comment sets the precedent: a job should be able to
+ * fail without taking an unrelated one down, and these two share nothing beyond
+ * the collection.
+ *
+ * Cloud Scheduler bills **per registered job** (3 free, 28 already registered),
+ * so this is ~$0.10/month — a cost the Firebase budget table explicitly accepts
+ * for a distinct cadence rather than contorting the schedule around it.
+ *
+ * 🛑 R1 is NOT here. It is folded into `paymentWindowTimeout` (every 5 minutes),
+ * because a webhook we received and lost should not wait up to 24 hours to be
+ * noticed — and its query is one indexed read, so the tight loop is free.
+ *
+ * 05:30 UTC = 11:00 IST, deliberately after `countersReconcile` (03:00) and
+ * `autoPayoutEligibility` so a payout decision is never taken on the same tick
+ * as the reconciliation that might open a case blocking it.
+ */
+/**
+ * Every deadline in the order lifecycle — one job, every 5 minutes.
+ *
+ * 🛑 ONE JOB FOR ~20 SCENARIOS, and the Scheduler count goes DOWN.
+ *
+ * The alternative was a cron per scenario, which is ~$2/month *and* `O(n²)`
+ * coverage reasoning — D25, D27 and the duplicate buyout notification are all
+ * that pattern failing. Here it is one indexed query per tick, empty when idle,
+ * and `obligations`' deterministic document id gives "at most one open
+ * obligation per (subject, kind)" so a double reconcile is a no-op.
+ *
+ * Phase 8 retires `paymentWindowTimeout`, `pendingOrderTimeout` and
+ * `paymentReviewAutoApprove` once their policy rows are proven, taking the
+ * registered count **28 → 29 → 27**.
+ *
+ * 🛑 NOT a Firestore trigger on `orders`. A trigger writing `obligations`
+ * whose sweep writes `orders` is Root Cause #92's self-write loop — the one
+ * that cost 1,017,548 invocations in 24 hours. Obligations are reconciled
+ * inside the order's own write, where the document is already in hand.
+ */
+export const obligationSweep = defineFunction({
+    name: "obligationSweep",
+    description: "Fire, warn on, or escalate every order-lifecycle deadline that has come due (every 5 minutes).",
+    trigger: { kind: "schedule", cron: EVERY_5_MIN },
+    handler: obligationSweepHandler,
+    options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
+});
+export const paymentReconcile = defineFunction({
+    name: "paymentReconcile",
+    description: "Reconcile the gateway's payments, refunds and disputes against our orders; open paymentCases (daily 05:30 UTC).",
+    trigger: { kind: "schedule", cron: "30 5 * * *", timeZone: "UTC" },
+    handler: paymentReconcileHandler,
+    options: { region: REGION, timeoutSeconds: 540, memory: "256MiB", maxInstances: 1 },
+});
+/**
+ * 🛑 ITS OWN FUNCTION, AND DELIBERATELY NOT A FIRESTORE TRIGGER.
+ *
+ * A trigger on `inventoryPlacements` writing back to `storageBoxes` would fire
+ * on every pick, move and receive — a 50-row receive is 50 placement writes and
+ * would wake it 50 times to recompute the same two boxes. It is also one
+ * refactor away from Root Cause #92's shape, which cost 1,017,548 invocations
+ * in 24 hours against a 2M/month free quota.
+ *
+ * Nightly is right because the rollup is ADVISORY: every surface that must be
+ * correct reads placements directly (the box detail page does, and says so),
+ * so a day-stale rollup costs a slightly wrong number in a list and never a
+ * wrong decision.
+ *
+ * 🛑 06:15 UTC, AND THE SLOT WAS CHOSEN BY COUNTING, NOT BY EYE. My first
+ * pick was 04:30 with a comment claiming it kept three collection-walking jobs
+ * out of the same minute — while `30 4 * * *` ALREADY held two
+ * (`priceIndexRollup` at 540s/512MiB among them), so it would have made three
+ * and the comment would have asserted the opposite of what it did.
+ *
+ * `grep -o 'cron: "…"' | sort | uniq -c` over this file is the check: 06:15 is
+ * empty, clear of the dense 00:00–05:30 band and of the 10:00 IST digest.
+ */
+export const boxRollupReconcile = defineFunction({
+    name: "boxRollupReconcile",
+    description: "Recompute each storage box's product/unit rollup from its real placements (daily 06:15 UTC).",
+    trigger: { kind: "schedule", cron: "15 6 * * *", timeZone: "UTC" },
+    handler: boxRollupReconcileHandler,
+    options: { region: REGION, timeoutSeconds: 540, memory: "256MiB", maxInstances: 1 },
+});
 export const positionsReconcile = defineFunction({
     name: "positionsReconcile",
     description: "Reconcile bid/auction positions (daily 03:30 UTC).",
@@ -300,6 +410,7 @@ export const SCHEDULED_FUNCTIONS = [
     productStatsSync,
     revenueRollup,
     priceIndexRollup,
+    marketPriceRollup,
     searchIndexBuild,
     analyticsAlertEvaluate,
     pageViewRollup,
@@ -307,6 +418,18 @@ export const SCHEDULED_FUNCTIONS = [
     dailyStatusDigest,
     dailyDataCleanup,
     countersReconcile,
+    /*
+     * 🛑 Registering here is NOT optional and is easy to miss: `defineFunction`
+     * only creates the definition — `SCHEDULED_FUNCTIONS` is what
+     * `APPKIT_FUNCTIONS` spreads and `bindAllFromRegistry` binds. A function
+     * defined and not listed deploys nowhere and NOTHING ERRORS: the export
+     * exists, the file compiles, and the job simply never runs. That is the same
+     * silent-omission shape as `audit-barrel-no-seed`'s (an export whose absence
+     * makes a loader quietly skip a collection).
+     */
+    paymentReconcile,
+    obligationSweep,
+    boxRollupReconcile,
     positionsReconcile,
     cartPrune,
     notificationPrune,

package/dist/_internal/server/jobs/core/autoPayoutEligibility.js

@@ -1,28 +1,58 @@
 import { orderRepository, payoutRepository, storeRepository, userRepository, siteSettingsRepository, } from "../../../../repositories/index.js";
 import { getDefaultCurrency } from "../../../../core/index.js";
 import { computePayoutDeduction } from "../../../shared/fees/calculator.js";
-import { ordersTaxableValue } from "../../../shared/checkout/order-math.js";
+import { payoutCutoff } from "../../../shared/fees/payout-hold.js";
+import { PROTECTION_CLAIM_WINDOW_HOURS } from "../../../shared/features/shipping/protections.js";
+import { ordersTaxableValue, ordersShippingReimbursement, } from "../../../shared/checkout/order-math.js";
 import { BATCH_LIMIT } from "../handlers/messages.js";
-const AUTO_PAYOUT_WINDOW_DAYS = 7;
-function getBusinessDayCutoff(daysAgo) {
-    const now = new Date();
-    const cutoff = new Date(now);
-    cutoff.setUTCDate(cutoff.getUTCDate() - daysAgo);
-    cutoff.setUTCHours(4, 30, 0, 0);
-    return cutoff;
-}
+/*
+ * 🛑 `AUTO_PAYOUT_WINDOW_DAYS = 7` and `getBusinessDayCutoff` were REMOVED on
+ * 2026-10-21. Do not reinstate either.
+ *
+ * The constant was a hardcoded duplicate of `commissions.payoutHoldDays`,
+ * which no code read (D28) — so the admin-facing setting was inert while this
+ * number decided every payout.
+ *
+ * The helper was worse: it did `cutoff.setUTCDate(cutoff.getUTCDate() -
+ * daysAgo)`, i.e. it subtracted CALENDAR days under a name that said business
+ * days. Measured from Monday 2026-10-19, 7 business days back is 2026-10-08
+ * and that helper returned 2026-10-12 — **four calendar days short**, so the
+ * stated 7-business-day hold was really about five, and every hold spanning a
+ * weekend released early in the seller's favour with nothing recording that
+ * the stated hold had not been honoured.
+ *
+ * Both now come from `payoutCutoff`, which is shared with
+ * `weeklyPayoutEligibility` so the two sweeps cannot disagree about the hold —
+ * they did, and one of them had no cutoff at all.
+ */
 export async function runAutoPayoutEligibility(ctx) {
     // `FEATURE_PAYOUTS` gate deleted 2026-10-19 — see `auctionSettlement.ts`.
     // This was the one flag actually set (`functions/.env.letitrip-in-app`), so
     // unlike its four siblings this job was running; removing the gate is a
     // no-op in behaviour and removes the lever that could silently stop payouts.
-    ctx.logger.info("Starting daily auto-payout eligibility sweep", {
-        windowDays: AUTO_PAYOUT_WINDOW_DAYS,
-    });
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings.commissions;
-    const cutoff = getBusinessDayCutoff(AUTO_PAYOUT_WINDOW_DAYS);
-    const eligible = await orderRepository.getEligibleAutomatic(cutoff);
+    const { cutoff, hold } = payoutCutoff({
+        payoutHoldDays: commissions?.payoutHoldDays,
+        returnWindowDays: siteSettings.returns?.windowDays,
+        maxClaimWindowHours: Math.max(PROTECTION_CLAIM_WINDOW_HOURS.shipping, PROTECTION_CLAIM_WINDOW_HOURS.sale),
+    }, { onWarn: (m, meta) => ctx.logger.warn(m, meta) });
+    /*
+     * Log the hold AND which input won. The admin setting is seeded at 2 days
+     * against a 7-day floor, so the honoured value will usually not be the one
+     * they configured — saying `source: "floor"` is what stops that reading as
+     * a bug to whoever set it.
+     */
+    ctx.logger.info("Starting daily auto-payout eligibility sweep", {
+        holdDays: hold.days,
+        holdSource: hold.source,
+        floorDays: hold.floor,
+        configured: commissions?.payoutHoldDays ?? null,
+        cutoff: cutoff.toISOString(),
+    });
+    const eligible = await orderRepository.getEligibleAutomatic(cutoff, {
+        onWarn: (m, meta) => ctx.logger.warn(m, meta),
+    });
     if (eligible.length === 0) {
         ctx.logger.info("No auto-payout eligible orders found");
         return;
@@ -82,7 +112,15 @@ export async function runAutoPayoutEligibility(ctx) {
          *     so the goods value still has our GST inside it.
          */
         const grossAmount = ordersTaxableValue(orders.map((o) => o.data));
-        const { platformFee, gatewayFee, gstOnFee: gstAmount, netAmount } = computePayoutDeduction(grossAmount, commissions);
+        const { platformFee, gatewayFee, gstOnFee: gstAmount, netAmount } = computePayoutDeduction(grossAmount, commissions, 
+        /*
+         * D45 — postage refunded to the seller, added AFTER the fee bases so no
+         * commission is charged on a cost being refunded. `.data` for the same
+         * reason `ordersTaxableValue` above needs it: `orders` holds
+         * `{ id, data }` wrappers, and passing the wrapper would read every field
+         * as undefined and silently reimburse zero.
+         */
+        ordersShippingReimbursement(orders.map((o) => o.data)));
         const payoutInput = {
             storeId,
             // `displayName` is plaintext by D1; the email fallback must be revealed.
@@ -121,7 +159,15 @@ export async function runAutoPayoutEligibility(ctx) {
                     bankName: sellerPlain.payoutDetails.bankAccount.bankName,
                 }
                 : undefined,
-            notes: `Auto-payout — ${orders.length} delivered order(s) past ${AUTO_PAYOUT_WINDOW_DAYS}-day window`,
+            /*
+             * 🛑 `hold.days`, NOT the deleted `AUTO_PAYOUT_WINDOW_DAYS`. This note
+             * still named the constant that was removed on 2026-10-21 for being a
+             * hardcoded duplicate of `commissions.payoutHoldDays` — see the header.
+             * Reinstating it is explicitly forbidden there, and it would also make
+             * the note LIE: `hold.days` is the value actually honoured, which is
+             * the floor or the admin setting, whichever won.
+             */
+            notes: `Auto-payout — ${orders.length} delivered order(s) past the ${hold.days}-day hold`,
             requestedAt: new Date(),
         };
         const { id: payoutId } = await payoutRepository.createPayout(payoutInput);

package/dist/_internal/server/jobs/core/boxRollupReconcile.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Recompute every storage box's `rollup` from its real placements.
+ *
+ * ── WHY A JOB AND NOT A TRIGGER ─────────────────────────────────────────────
+ *
+ * `rollup` exists so the boxes LIST can show "8 products · 23 units" without
+ * one placements query per row. It is a cache, and this is its only writer.
+ *
+ * 🛑 DELIBERATELY NOT A FIRESTORE TRIGGER ON `inventoryPlacements`. A trigger
+ * that watched placements and wrote back to `storageBoxes` would fire on every
+ * single pick, move and receive — a 50-row receive is 50 placement writes and
+ * would wake it 50 times to recompute the same two boxes. Worse, it is one
+ * refactor away from Root Cause #92's shape: a trigger whose write-back lands
+ * in a collection it also watches, which cost this project 1,017,548
+ * invocations in 24 hours against a 2M/month free quota.
+ *
+ * A nightly pass is the right cadence BECAUSE THE CACHE IS ADVISORY. Every
+ * surface that must be correct reads placements directly — the box detail page
+ * does, and its own note says why — so a rollup up to a day stale costs a
+ * slightly wrong number in a list, never a wrong decision.
+ *
+ * ── WHAT IT FIXES, AS OPPOSED TO MAINTAINS ──────────────────────────────────
+ *
+ * It is a REPAIR job, which is the lesson from Root Cause #102: a reconciler
+ * must enumerate the ENTITIES, not the events, or it can only ever add. A box
+ * whose last product was picked yesterday has no placements at all — so a pass
+ * built from placements would never visit it, and it would keep advertising
+ * the count it had when it was last full. Walking `storageBoxes` and treating
+ * "no placements" as a real zero is the whole point.
+ *
+ * It also logs `drifted`. On a quiet day that number should be 0, and a
+ * non-zero one is a real signal that something wrote placements without the
+ * repository — which `audit-inventory-ledger-append-only` is supposed to make
+ * impossible.
+ *
+ * @tag domain:inventory
+ * @tag layer:job
+ * @tag access:server
+ */
+import type { JobContext } from "../runtime/types";
+export interface BoxRollupReconcileResult {
+    boxesVisited: number;
+    drifted: number;
+    written: number;
+}
+export declare function runBoxRollupReconcile(ctx: JobContext): Promise<BoxRollupReconcileResult>;

package/dist/_internal/server/jobs/core/boxRollupReconcile.js

@@ -0,0 +1,142 @@
+/**
+ * Recompute every storage box's `rollup` from its real placements.
+ *
+ * ── WHY A JOB AND NOT A TRIGGER ─────────────────────────────────────────────
+ *
+ * `rollup` exists so the boxes LIST can show "8 products · 23 units" without
+ * one placements query per row. It is a cache, and this is its only writer.
+ *
+ * 🛑 DELIBERATELY NOT A FIRESTORE TRIGGER ON `inventoryPlacements`. A trigger
+ * that watched placements and wrote back to `storageBoxes` would fire on every
+ * single pick, move and receive — a 50-row receive is 50 placement writes and
+ * would wake it 50 times to recompute the same two boxes. Worse, it is one
+ * refactor away from Root Cause #92's shape: a trigger whose write-back lands
+ * in a collection it also watches, which cost this project 1,017,548
+ * invocations in 24 hours against a 2M/month free quota.
+ *
+ * A nightly pass is the right cadence BECAUSE THE CACHE IS ADVISORY. Every
+ * surface that must be correct reads placements directly — the box detail page
+ * does, and its own note says why — so a rollup up to a day stale costs a
+ * slightly wrong number in a list, never a wrong decision.
+ *
+ * ── WHAT IT FIXES, AS OPPOSED TO MAINTAINS ──────────────────────────────────
+ *
+ * It is a REPAIR job, which is the lesson from Root Cause #102: a reconciler
+ * must enumerate the ENTITIES, not the events, or it can only ever add. A box
+ * whose last product was picked yesterday has no placements at all — so a pass
+ * built from placements would never visit it, and it would keep advertising
+ * the count it had when it was last full. Walking `storageBoxes` and treating
+ * "no placements" as a real zero is the whole point.
+ *
+ * It also logs `drifted`. On a quiet day that number should be 0, and a
+ * non-zero one is a real signal that something wrote placements without the
+ * repository — which `audit-inventory-ledger-append-only` is supposed to make
+ * impossible.
+ *
+ * @tag domain:inventory
+ * @tag layer:job
+ * @tag access:server
+ */
+import { INVENTORY_PLACEMENTS_COLLECTION, STORAGE_BOXES_COLLECTION, } from "../../../../features/inventory/schemas/firestore.js";
+/** Pages rather than `.limit(1000)` — see the note at the call. */
+const BOX_PAGE = 200;
+export async function runBoxRollupReconcile(ctx) {
+    const db = ctx.db;
+    let boxesVisited = 0;
+    let drifted = 0;
+    let written = 0;
+    /*
+     * 🛑 PAGINATED, NOT `.limit(N)`. A truncated reconcile is indistinguishable
+     * from a complete one — it logs "reconciliation complete" having silently
+     * ignored every box past the cap, which is exactly how the counters job
+     * under-reported for weeks (Root Cause #102). Ordering by document id gives
+     * a stable cursor with no index.
+     */
+    let cursor = null;
+    for (;;) {
+        let q = db
+            .collection(STORAGE_BOXES_COLLECTION)
+            .orderBy("__name__")
+            .limit(BOX_PAGE);
+        if (cursor)
+            q = q.startAfter(cursor);
+        const page = await q.get();
+        if (page.empty)
+            break;
+        for (const doc of page.docs) {
+            boxesVisited += 1;
+            const box = doc.data();
+            /*
+             * One query per box. Bounded and cheap — a box holds tens of products,
+             * not thousands — and `.select()` fetches only the two fields the tally
+             * needs rather than every placement's denormalised title and SKU.
+             */
+            const placements = await db
+                .collection(INVENTORY_PLACEMENTS_COLLECTION)
+                .where("boxId", "==", doc.id)
+                .select("quantity")
+                .get();
+            let distinctProducts = 0;
+            let totalUnits = 0;
+            for (const p of placements.docs) {
+                const qty = p.data()
+                    .quantity;
+                /*
+                 * A zero- or negative-quantity placement should not exist — `pick`
+                 * deletes at zero — so it is counted as neither a product nor a unit
+                 * and reported, rather than quietly inflating `distinctProducts` with
+                 * a row representing nothing.
+                 */
+                if (!(typeof qty === "number" && qty > 0))
+                    continue;
+                distinctProducts += 1;
+                totalUnits += qty;
+            }
+            const prior = box.rollup;
+            const changed = !prior ||
+                prior.distinctProducts !== distinctProducts ||
+                prior.totalUnits !== totalUnits;
+            if (!changed)
+                continue;
+            drifted += 1;
+            /*
+             * A direct `update`, not `storageBoxesRepository.setRollup`. The job
+             * owns thousands of these and a repository call per box would re-read
+             * the document it already holds — and the repository's own note says
+             * `setRollup` is for a caller that has a box id and nothing else.
+             *
+             * Only the three rollup fields plus `updatedAt` are written: a merge of
+             * the whole document would resurrect any field a concurrent edit had
+             * just cleared.
+             */
+            /*
+             * `ctx.now`, not `new Date()`. Every box in one pass then carries the
+             * SAME `computedAt`, so "as of" on a printed label means the pass rather
+             * than the millisecond that box happened to be reached — and two boxes
+             * reconciled by one run cannot appear to have been counted minutes
+             * apart.
+             */
+            await doc.ref.update({
+                rollup: { distinctProducts, totalUnits, computedAt: ctx.now },
+                updatedAt: ctx.now,
+            });
+            written += 1;
+        }
+        if (page.size < BOX_PAGE)
+            break;
+        cursor = page.docs[page.docs.length - 1].id;
+    }
+    /*
+     * `drifted` is the signal, not `boxesVisited`. Every placement write goes
+     * through the repository, which keeps nothing cached — so on a quiet day
+     * this should be the number of boxes whose contents actually changed since
+     * the last pass. A number far larger than that, or one that never falls,
+     * means something is writing placements outside the repository.
+     */
+    ctx.logger.info("boxRollupReconcile complete", {
+        boxesVisited,
+        drifted,
+        written,
+    });
+    return { boxesVisited, drifted, written };
+}