@mohasinac/appkit 4.62.0 → 4.62.1

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

@@ -5,55 +5,88 @@
  * (CLAUDE.md Rule #6 — Vercel routes never do heavy work; they write a
  * `jobs` doc and return, this Function does the actual processing).
  *
- * Flow:
- *   1. Mark the job "processing".
- *   2. Look up a runner in `JOB_RUNNERS` by `job.jobType`.
- *   3. Run it, mark the job "done"/"failed", and best-effort ping the
- *      `bulk_events/{jobId}` RTDB channel the client is subscribed to via
- *      `useBulkEvent` — every RTDB write is its own try/catch so a ping
- *      failure never masks the real Firestore result.
+ * ## 🛑 It no longer runs the job itself — `runJobOnce` does (Phase 8)
+ *
+ * The attempt, the failure classification and the retry scheduling all live in
+ * `runJobOnce`, which the retry sweep also calls. One dispatch path for both
+ * entry points, or the two drift the first time either learns something.
  */
-import { normalizeError } from "../../../../errors/normalize.js";
 import { jobsRepository } from "../../../../repositories/index.js";
-import { getAdminRealtimeDb } from "../../../../providers/db-firebase/index.js";
-import { RTDB_PATHS } from "../../../../providers/db-firebase/rtdb-paths.js";
-import { JOB_RUNNERS } from "./jobRunners.js";
-async function pingBulkEvent(jobId, payload, ctx) {
-    try {
-        await getAdminRealtimeDb()
-            .ref(`${RTDB_PATHS.BULK_EVENTS}/${jobId}`)
-            .set({ ...payload, updatedAt: Date.now() });
-    }
-    catch (err) {
-        void normalizeError(err);
-        ctx.logger.warn("onJobCreated: RTDB ping failed (non-fatal)", {
-            jobId,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-}
+import { runJobOnce } from "./runJobOnce.js";
 export async function handleJobCreated(input, ctx) {
     const { jobId, job } = input;
-    await jobsRepository.markProcessing(jobId);
-    const runner = JOB_RUNNERS[job.jobType];
-    if (!runner) {
-        const error = `No runner registered for jobType: ${job.jobType}`;
-        await jobsRepository.markFailed(jobId, error);
-        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error }, ctx);
-        ctx.logger.error("onJobCreated: unregistered jobType", null, { jobId, jobType: job.jobType });
-        return;
-    }
-    try {
-        const result = await runner(job.payload, ctx);
-        await jobsRepository.markDone(jobId, result);
-        await pingBulkEvent(jobId, { status: "success", action: job.jobType, ...result }, ctx);
-        ctx.logger.info("onJobCreated: job complete", { jobId, jobType: job.jobType, summary: result.summary });
+    /*
+     * ── 🛑 A SCHEDULED RETRY MUST NOT RUN HERE ────────────────────────────────
+     *
+     * This guard is the whole reason Phase 8's backoff works, and its absence
+     * was a defect in this feature's own first draft.
+     *
+     * A retry is a NEW `jobs` document (it has to be — this trigger fires on
+     * CREATE, so flipping a job back to `pending` would never wake anything).
+     * But creating that document fires THIS trigger immediately — so without
+     * this check, every retry would run the instant it was scheduled, the
+     * 5-minute and 30-minute backoffs would be zero, and three attempts would
+     * burn in under a second against a fault that had not had time to clear.
+     * The backoff fields would still be written, so the database would read as
+     * though it had waited.
+     *
+     * `nextAttemptAt` in the future means "the sweep owns this one". Returning
+     * leaves the document `pending`, which is exactly what `getDueRetries`
+     * queries for.
+     */
+    if (job.nextAttemptAt) {
+        const due = new Date(job.nextAttemptAt).getTime();
+        if (Number.isFinite(due) && due > Date.now()) {
+            ctx.logger.info("onJobCreated: retry scheduled, deferring to the sweep", {
+                jobId,
+                jobType: job.jobType,
+                attempt: job.attempt ?? 1,
+                nextAttemptAt: new Date(due).toISOString(),
+            });
+            return;
+        }
     }
-    catch (err) {
-        void normalizeError(err);
-        const message = err instanceof Error ? err.message : String(err);
-        await jobsRepository.markFailed(jobId, message);
-        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error: message }, ctx);
-        ctx.logger.error("onJobCreated: job failed", err, { jobId, jobType: job.jobType });
+    await runJobOnce({ jobId, job }, ctx);
+}
+/**
+ * The retry sweep — runs every scheduled attempt whose time has come.
+ *
+ * ## 🛑 Folded into an EXISTING scheduled function, not a new one
+ *
+ * It is called from `paymentWindowTimeout` (every 5 minutes). Cloud Scheduler
+ * bills per registered job and this project already carries ~34 of them
+ * against 3 free; adding a 35th to run a usually-empty query is the cost this
+ * plan explicitly refuses. The same reasoning put the ledger reconciler inside
+ * `dailyDataCleanup` and R1 inside this same function.
+ *
+ * 🛑 And it is placed FIRST at its call site, before that function's early
+ * return — `paymentWindowTimeout` returns as soon as there are no expired
+ * payment windows, which is most ticks, so appending would run the sweep only
+ * on the minority of ticks with unrelated work (Root Cause #27).
+ *
+ * Sequential, not `Promise.all`. A job runner is heavy by definition — that is
+ * why it is a job — and twenty of them concurrently inside one 540s function
+ * is how a sweep exhausts its own budget. Twenty sequential attempts that run
+ * out of time simply leave the rest `pending` for the next tick, which is the
+ * safe failure.
+ */
+export async function runDueJobRetries(ctx) {
+    const due = await jobsRepository.getDueRetries();
+    if (due.length === 0)
+        return { ran: 0 };
+    ctx.logger.info("job retries: running due attempts", { count: due.length });
+    let ran = 0;
+    for (const { id, data } of due) {
+        /*
+         * `runJobOnce` never throws — it records every outcome on the job itself.
+         * The `.catch` is belt-and-braces so one pathological job cannot abort the
+         * rest of the sweep, which would leave the remainder un-retried with no
+         * record of why.
+         */
+        await runJobOnce({ jobId: id, job: data }, ctx).catch((err) => {
+            ctx.logger.error("job retries: attempt threw", err, { jobId: id });
+        });
+        ran += 1;
     }
+    return { ran };
 }

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

@@ -6,9 +6,16 @@ export type OrderAfter = {
     userEmail: string;
     productTitle: string;
     trackingNumber?: string;
+    /**
+     * Phase 7 — the invoice is numbered on the PAYMENT transition, which is a
+     * different axis from `status` and is why these two fields are here.
+     */
+    paymentStatus?: string;
+    invoiceNumber?: string;
 };
 export type OrderBefore = {
     status: OrderStatus;
+    paymentStatus?: string;
 };
 export interface HandleOrderStatusChangeInput {
     orderId: string;

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

@@ -1,5 +1,9 @@
 import { decryptPii } from "../../../../security/index.js";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+/* Phase 7 — numbering only; the PDF renderer lives in `functions/` because
+ * `pdfkit` must not enter appkit's module graph. */
+import { allocateSeriesNumber } from "../../features/invoicing/allocate.js";
 import { ORDER_MESSAGES } from "../handlers/messages.js";
 const STATUS_CONFIG = {
     confirmed: {
@@ -31,6 +35,64 @@ export async function handleOrderStatusChange(input, ctx) {
     const { orderId, before, after } = input;
     if (!before || !after)
         return;
+    /*
+     * ── PHASE 7: number the invoice on the PAYMENT transition ─────────────────
+     *
+     * 🛑 PLACED FIRST, before the `status`-unchanged early return. That return
+     * is correct for the notification work below it, and it is also why this
+     * cannot go after it: `paymentStatus: pending → paid` frequently happens
+     * with NO change to `status` at all (a COD order verified by an admin, a
+     * manual proof approved), so appending this below would have numbered only
+     * the minority of paid orders whose status happened to move in the same
+     * write. That is Root Cause #27's sweep-coverage trap, and R1 in
+     * `paymentWindowTimeout` had to be placed the same way for the same reason.
+     *
+     * 🛑 Extending THIS trigger rather than adding a second one on `orders`.
+     * A second Firestore trigger on the same collection wakes for every write
+     * and returns — which is how `onShipmentDeleted` burned a million
+     * invocations a day sitting correctly-guarded beside a neighbour's loop
+     * (Root Cause #92). The sticker-trace definitions carry the same 🛑.
+     *
+     * 🛑 And it is numbering ONLY — no PDF. `pdfkit` is a Functions dependency
+     * and must not enter appkit's module graph; the bytes are rendered once,
+     * lazily, by the serve route and stored from there. Numbering is the half
+     * that must be immediate and transactional, because it is the half that
+     * cannot be corrected: a number cannot be withdrawn without leaving a gap.
+     */
+    const becamePaid = before.paymentStatus !== "paid" && after.paymentStatus === "paid";
+    if (becamePaid && !after.invoiceNumber) {
+        try {
+            const allocation = await allocateSeriesNumber({
+                kind: "invoice",
+                subjectId: orderId,
+                orderId,
+            });
+            /*
+             * Only writes when THIS call allocated. A re-entry that found an
+             * existing claim skips the write entirely, which keeps a re-fired
+             * trigger from touching the order at all — the write that would
+             * otherwise re-fire this very trigger.
+             */
+            if (allocation.allocated) {
+                await orderRepository.update(orderId, {
+                    invoiceNumber: allocation.number,
+                    invoiceIssuedAt: new Date(),
+                });
+                ctx.logger.info(`Invoice ${allocation.number} allocated`, { orderId });
+            }
+        }
+        catch (error) {
+            /*
+             * Logged and swallowed, so a numbering failure cannot suppress the
+             * buyer's order notification below. The order stays un-invoiced, which
+             * is a visible, retryable state — the next write that touches
+             * `paymentStatus` re-attempts, and the serve route can allocate on
+             * demand. Throwing here would also make the Firestore trigger retry the
+             * whole handler, re-sending the notification.
+             */
+            ctx.logger.error("Invoice allocation failed", error, { orderId });
+        }
+    }
     if (before.status === after.status)
         return;
     const newStatus = after.status;

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

@@ -6,6 +6,9 @@ import { OrderStatusValues } from "../../../../features/orders/schemas/firestore
 import { PAYMENT_WINDOW_EXPIRED_REASON } from "../../../../features/orders/constants/payment-window.js";
 import { ORDER_MESSAGES } from "../handlers/messages.js";
 import { reconcileStuckGatewayEvents } from "./paymentReconcile.js";
+/* Phase 8 — the job retry sweep. Folded in here rather than given its own
+ * Scheduler job; see its own docstring and the 🛑 at the call site. */
+import { runDueJobRetries } from "./onJobCreated.js";
 /**
  * 15-minute payment window sweep — cancels + restocks any `upi_manual`/
  * `cash`/`emi` order still `pending`/`pending` with no proof uploaded past
@@ -53,6 +56,36 @@ export async function runPaymentWindowTimeout(ctx) {
             err,
         });
     }
+    /*
+     * ── Phase 8 rides along too: job retries whose backoff has elapsed ────────
+     *
+     * Same two reasons as R1 above, and the same placement rule: **FIRST, before
+     * the early return**. A retry is a `pending` job document with a future
+     * `nextAttemptAt`, and nothing else in the system will ever run it — the
+     * create trigger deliberately defers to this sweep, because creating the
+     * retry document fires that trigger instantly and would collapse the backoff
+     * to zero.
+     *
+     * So if this call sat after the early return, a retry would run only on a
+     * tick that happened to have an expired payment window — which is the
+     * minority — and a job scheduled on a quiet afternoon could wait hours.
+     * Root Cause #27 again, now with a second mechanism depending on it.
+     *
+     * Never throws, for the same reason R1 does not: a stuck job must not stop
+     * the payment-window cancellations this function exists for.
+     */
+    try {
+        const retries = await runDueJobRetries(ctx);
+        if (retries.ran > 0) {
+            ctx.logger.info("Phase 8: ran due job retries", { ...retries });
+        }
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("job retry sweep failed inside paymentWindowTimeout — continuing", {
+            err,
+        });
+    }
     ctx.logger.info("Scanning orders past their 15-minute payment deadline");
     const expired = await orderRepository.getExpiredPaymentDeadlines();
     if (expired.length === 0) {

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

@@ -0,0 +1,48 @@
+/**
+ * Run ONE attempt of a job, and decide what happens next (Phase 8).
+ *
+ * ## 🛑 ONE dispatch path, shared by the trigger and the retry sweep
+ *
+ * `handleJobCreated` is the `jobs/{jobId}` create trigger; `runDueJobRetries`
+ * is the sweep that picks up scheduled retries. Both call THIS, so there is
+ * exactly one place that knows how to run a job, classify its failure and
+ * schedule the next attempt. Two dispatch paths would drift the first time one
+ * of them learned something — which is the shape of every defect in this
+ * plan's § "Recurrent Root Cause Patterns" that begins "a fix applied to the
+ * route but never back-ported".
+ *
+ * ## 🛑 A retry is a NEW DOCUMENT
+ *
+ * `onJobCreated` fires on CREATE. Re-running a job by flipping its status back
+ * to `pending` would never wake the trigger, so the job would sit `pending`
+ * forever looking scheduled — a stall that reads as "queued". So a retry is a
+ * fresh `jobs` document carrying `attempt + 1`, `parentJobId` and a
+ * `nextAttemptAt`, and the sweep is what runs it when due.
+ *
+ * ## What is retryable
+ *
+ * `mapToHttpError(err).status >= 500`. Reused rather than invented: that
+ * function already encodes "is this our fault or the caller's" for every error
+ * class in the codebase, and a second classification would answer differently
+ * the first time either changed.
+ *
+ * A 4xx is terminal IMMEDIATELY — no backoff, no attempts burned. A validation
+ * failure does not become valid by waiting, and retrying it three times over
+ * 35 minutes just delays the case by 35 minutes.
+ */
+import { type JobDocument } from "../../../../features/jobs/schemas/firestore";
+import type { JobContext } from "../runtime/types";
+export interface RunJobOnceInput {
+    jobId: string;
+    job: JobDocument;
+}
+/**
+ * Run one attempt. Marks the job done, schedules a retry, or declares it dead.
+ *
+ * Never throws: a job's failure is recorded on the job, and letting it escape
+ * would make the Firebase trigger retry the whole handler — a second,
+ * uncontrolled retry mechanism layered under this one, which is precisely the
+ * doubling that cost 55 sessions in Root Cause #91 (`run.mjs`'s internal retry
+ * multiplying the pool's).
+ */
+export declare function runJobOnce(input: RunJobOnceInput, ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,195 @@
+/**
+ * Run ONE attempt of a job, and decide what happens next (Phase 8).
+ *
+ * ## 🛑 ONE dispatch path, shared by the trigger and the retry sweep
+ *
+ * `handleJobCreated` is the `jobs/{jobId}` create trigger; `runDueJobRetries`
+ * is the sweep that picks up scheduled retries. Both call THIS, so there is
+ * exactly one place that knows how to run a job, classify its failure and
+ * schedule the next attempt. Two dispatch paths would drift the first time one
+ * of them learned something — which is the shape of every defect in this
+ * plan's § "Recurrent Root Cause Patterns" that begins "a fix applied to the
+ * route but never back-ported".
+ *
+ * ## 🛑 A retry is a NEW DOCUMENT
+ *
+ * `onJobCreated` fires on CREATE. Re-running a job by flipping its status back
+ * to `pending` would never wake the trigger, so the job would sit `pending`
+ * forever looking scheduled — a stall that reads as "queued". So a retry is a
+ * fresh `jobs` document carrying `attempt + 1`, `parentJobId` and a
+ * `nextAttemptAt`, and the sweep is what runs it when due.
+ *
+ * ## What is retryable
+ *
+ * `mapToHttpError(err).status >= 500`. Reused rather than invented: that
+ * function already encodes "is this our fault or the caller's" for every error
+ * class in the codebase, and a second classification would answer differently
+ * the first time either changed.
+ *
+ * A 4xx is terminal IMMEDIATELY — no backoff, no attempts burned. A validation
+ * failure does not become valid by waiting, and retrying it three times over
+ * 35 minutes just delays the case by 35 minutes.
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { mapToHttpError } from "../../../../errors/error-mapping.js";
+import { jobsRepository } from "../../../../repositories/index.js";
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
+import { getAdminRealtimeDb } from "../../../../providers/db-firebase/index.js";
+import { RTDB_PATHS } from "../../../../providers/db-firebase/rtdb-paths.js";
+import { JOB_BACKOFF_MS, JOB_MAX_ATTEMPTS, } from "../../../../features/jobs/schemas/firestore.js";
+import { JOB_RUNNERS } from "./jobRunners.js";
+async function pingBulkEvent(jobId, payload, ctx) {
+    try {
+        await getAdminRealtimeDb()
+            .ref(`${RTDB_PATHS.BULK_EVENTS}/${jobId}`)
+            .set({ ...payload, updatedAt: Date.now() });
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.warn("runJobOnce: RTDB ping failed (non-fatal)", {
+            jobId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * The delay before the next attempt.
+ *
+ * 🛑 Clamped to the LAST element rather than indexing past the end. An
+ * out-of-range index yields `undefined`, `new Date(Date.now() + undefined)` is
+ * `Invalid Date`, and the sweep's `nextAttemptAt <= now` comparison is false
+ * for an invalid date forever — so the retry would be scheduled and never run.
+ * A stall that looks like a queue is the exact failure this phase removes.
+ */
+function backoffFor(attempt) {
+    const idx = Math.max(0, Math.min(attempt - 1, JOB_BACKOFF_MS.length - 1));
+    return JOB_BACKOFF_MS[idx];
+}
+/**
+ * Run one attempt. Marks the job done, schedules a retry, or declares it dead.
+ *
+ * Never throws: a job's failure is recorded on the job, and letting it escape
+ * would make the Firebase trigger retry the whole handler — a second,
+ * uncontrolled retry mechanism layered under this one, which is precisely the
+ * doubling that cost 55 sessions in Root Cause #91 (`run.mjs`'s internal retry
+ * multiplying the pool's).
+ */
+export async function runJobOnce(input, ctx) {
+    const { jobId, job } = input;
+    const attempt = job.attempt ?? 1;
+    const maxAttempts = job.maxAttempts ?? JOB_MAX_ATTEMPTS;
+    await jobsRepository.markProcessing(jobId);
+    const runner = JOB_RUNNERS[job.jobType];
+    if (!runner) {
+        /*
+         * 🛑 Terminal immediately, and DEAD rather than failed. An unregistered
+         * jobType cannot become registered by waiting, and the thing that would
+         * fix it is a deploy — so this is the clearest possible case for a human,
+         * not a retry. It is also the failure mode of the seed-loader registry
+         * (Root Cause #90): a missing map entry whose symptom is silence.
+         */
+        const error = `No runner registered for jobType: ${job.jobType}`;
+        await jobsRepository.markDead(jobId, error);
+        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error }, ctx);
+        await openDeadJobCase(jobId, job, error, ctx);
+        ctx.logger.error("runJobOnce: unregistered jobType", null, { jobId, jobType: job.jobType });
+        return;
+    }
+    try {
+        const result = await runner(job.payload, ctx);
+        await jobsRepository.markDone(jobId, result);
+        await pingBulkEvent(jobId, { status: "success", action: job.jobType, ...result }, ctx);
+        ctx.logger.info("runJobOnce: job complete", {
+            jobId,
+            jobType: job.jobType,
+            attempt,
+            summary: result.summary,
+        });
+        return;
+    }
+    catch (err) {
+        void normalizeError(err);
+        const message = err instanceof Error ? err.message : String(err);
+        /*
+         * 🛑 `mapToHttpError` rather than a bespoke test. It already decides "ours
+         * or theirs" for every error class here, so a 5xx is a transient fault
+         * worth retrying and a 4xx is a permanent one that will fail identically
+         * in five minutes.
+         */
+        const status = mapToHttpError(err).status;
+        const retryable = status >= 500;
+        const attemptsLeft = attempt < maxAttempts;
+        if (retryable && attemptsLeft) {
+            const nextAttemptAt = new Date(Date.now() + backoffFor(attempt));
+            /*
+             * 🛑 The NEW document is created BEFORE this one is marked failed. The
+             * reverse ordering leaves a window where the job reads as failed with no
+             * retry scheduled — and if the process dies in that window, nothing
+             * retries and nothing says so. This way the worst case is a scheduled
+             * retry whose parent still reads `processing`, which the sweep handles
+             * and a human can see.
+             */
+            const retryId = await jobsRepository.createRetry(jobId, job, {
+                attempt: attempt + 1,
+                maxAttempts,
+                nextAttemptAt,
+            });
+            await jobsRepository.markFailed(jobId, message);
+            /*
+             * The client is told "retrying", not "failed". `useBulkEvent` watches
+             * for a terminal state, and reporting failure here would stop a progress
+             * UI on a job that is still going.
+             */
+            await pingBulkEvent(jobId, { status: "retrying", action: job.jobType, error: message, retryJobId: retryId }, ctx);
+            ctx.logger.warn("runJobOnce: attempt failed, retry scheduled", {
+                jobId,
+                retryId,
+                jobType: job.jobType,
+                attempt,
+                status,
+                nextAttemptAt: nextAttemptAt.toISOString(),
+            });
+            return;
+        }
+        await jobsRepository.markDead(jobId, message);
+        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error: message }, ctx);
+        await openDeadJobCase(jobId, job, message, ctx);
+        ctx.logger.error("runJobOnce: job DEAD", err, {
+            jobId,
+            jobType: job.jobType,
+            attempt,
+            status,
+            reason: retryable ? "attempts exhausted" : "permanent failure",
+        });
+    }
+}
+/**
+ * A dead job is a case, not a log line.
+ *
+ * 🛑 Keyed on the ORIGINAL job id (`parentJobId ?? jobId`), so three exhausted
+ * attempts of one job produce ONE case rather than three. `openOrObserve`
+ * increments its own counter — the property that makes it safe to open a case
+ * from a hot path at all.
+ *
+ * Best-effort: a job is already dead by this point, and failing to file the
+ * case must not turn that into a thrown error from a trigger.
+ */
+async function openDeadJobCase(jobId, job, error, ctx) {
+    const subjectId = job.parentJobId ?? jobId;
+    try {
+        await paymentCasesRepository().openOrObserve({
+            kind: "dead_job",
+            subjectId,
+            severity: "error",
+            entityType: "job",
+            entityId: subjectId,
+            title: `Job ${job.jobType} gave up after ${job.attempt ?? 1} attempt(s)`,
+            detail: `The last error was: ${error}. ` +
+                `Requested by ${job.requestedBy}. The job document holds the payload.`,
+        });
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("runJobOnce: could not open dead_job case", err, { jobId });
+    }
+}

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

@@ -8,7 +8,7 @@ import { getDefaultCurrency } from "../../../../core/index.js";
 import { computePayoutDeduction } from "../../../shared/fees/calculator.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 { ordersTaxableValue, ordersShippingReimbursement, ordersPointsBorneByStore, } from "../../../shared/checkout/order-math.js";
 export async function runWeeklyPayoutEligibility(ctx) {
     // `FEATURE_PAYOUTS` gate deleted 2026-10-19 — see `autoPayoutEligibility.ts`.
     const siteSettings = await siteSettingsRepository.getSingleton();
@@ -75,7 +75,15 @@ export async function runWeeklyPayoutEligibility(ctx) {
          * `{ id, data }` wrappers, and passing the wrapper would read every field
          * as undefined and silently reimburse zero.
          */
-        ordersShippingReimbursement(orders.map((o) => o.data)));
+        ordersShippingReimbursement(orders.map((o) => o.data)), 
+        /*
+         * D46/D47 — the store-funded points, both ends. Must match
+         * `autoPayoutEligibility` exactly, for the reason stated above
+         * `grossAmount`: the weekly run and the automatic one pay the same orders,
+         * and a term present in one and absent in the other is a seller paid two
+         * different amounts depending on which job got there first.
+         */
+        ordersPointsBorneByStore(orders.map((o) => o.data)));
         /*
          * 🛑 REVEALED before building a payout — see the identical note in
          * `autoPayoutEligibility.ts`. `findById` is ciphertext-by-default and

package/dist/_internal/server/jobs/handlers/onOrderStatusChange.js

@@ -1,4 +1,21 @@
 import { handleOrderStatusChange, } from "../core/onOrderStatusChange.js";
+/*
+ * 🛑 Bound as **`documentUpdated`**, which is what Phase 7's numbering needs
+ * and is already what this function uses — verified rather than assumed.
+ *
+ * `paymentStatus: pending → paid` is frequently the ONLY field that moves on a
+ * COD or manual order, and `documentUpdated` fires on any update, so the
+ * handler sees it. `documentCreated` would miss every one of them, and
+ * `documentWritten` would add nothing except a wake-up on create, where an
+ * order is `pending` and there is nothing to number.
+ *
+ * 🛑 What makes a write-back from this handler safe is the allocation claim:
+ * it updates `orders` only when IT allocated, so the re-fire caused by its own
+ * write finds the claim taken and writes nothing. That is the guard Root Cause
+ * #92's 12M-invocation loop lacked — there the no-op check compared Firestore
+ * maps with `JSON.stringify`, which is key-order sensitive and could never
+ * match, so every invocation wrote and every write re-triggered.
+ */
 export const onOrderStatusChangeHandler = async (event, ctx) => {
     await handleOrderStatusChange({ orderId: event.params.orderId, before: event.before, after: event.after }, ctx);
 };

package/dist/_internal/server/notifications/channel-health.d.ts

@@ -10,10 +10,33 @@
  * its own outcome decides whether the circuit re-closes or re-opens.
  */
 /**
- * Email is the only outbound channel with a transport. "whatsapp" was the
- * other arm until 2026-10-20, when the Cloud API integration was removed.
+ * Email is the only outbound *notification* channel with a transport.
+ * "whatsapp" was the other arm until 2026-10-20, when the Cloud API
+ * integration was removed.
+ *
+ * ## 🛑 Phase 8 widened this to the RECONCILERS' reads — and only those
+ *
+ * `razorpay_read` and `shiprocket_read` name the one placement where "stop
+ * hammering a dead API" is the right behaviour. Two placements are **actively
+ * harmful** and must never be added:
+ *
+ * 1. **NOT the webhook ingest path.** An open breaker converts a transient
+ *    blip into a DROPPED money event — and dropping is precisely what a
+ *    breaker does. The ingest path's whole job is to persist first and ack
+ *    honestly so the gateway retries; a breaker there would ack a 5xx we never
+ *    recorded.
+ *
+ * 2. **NOT around `payment.refund()`.** A refund POST that timed out may have
+ *    SUCCEEDED, so retrying it issues two refunds — and the idempotency claim
+ *    does not help, because it is the same call with the same key making a
+ *    second network attempt. The two-phase reserve/settle exists so a human
+ *    can resolve that by reading the gateway, not so a breaker can guess.
+ *
+ * The names carry `_read` for exactly that reason: a reader is idempotent, so
+ * backing off costs only freshness. Anything that moves money is not a reader
+ * and does not belong in this union.
  */
-export type NotificationChannel = "email";
+export type NotificationChannel = "email" | "razorpay_read" | "shiprocket_read";
 /**
  * Returns false only when the circuit is open and still within its cooldown
  * window. Any other state (closed, or open-but-cooldown-elapsed) is treated

package/dist/_internal/shared/actions/action-registry.js

@@ -3256,6 +3256,34 @@ export const ACTIONS = {
                 confirmLabel: "Close ticket",
             },
         },
+        /*
+         * Raising a dispute on an order.
+         *
+         * Filed under SUPPORT rather than a new ORDER bucket: there is no such
+         * bucket, and a dispute's destination is a support investigation. A first
+         * draft of the form wrote `ACTIONS.ORDERS?.["raise-dispute"]`, where the
+         * optional chain would have silently resolved to `undefined` and rendered
+         * a button with no label, no aria-label and no confirmation — which is
+         * precisely what Rule #7 exists to stop.
+         *
+         * NO `confirmation`, deliberately. It is not destructive: nothing is
+         * cancelled, no money moves, and the action's own docstring says it "does
+         * not itself reverse payment/order status". A confirm dialog in front of
+         * "tell us something went wrong" adds friction to the one path a buyer
+         * with a problem needs to be able to take.
+         */
+        "raise-dispute": {
+            // `report`, which IS the Flag glyph (icon-registry.ts:133). `"flag"` is
+            // not a registered key — and because `iconKey` is typed `IconKey` rather
+            // than `string`, that would have been a compile error rather than the
+            // silent no-op it used to be.
+            iconKey: "report",
+            id: "support.raise-dispute",
+            label: "Report this",
+            ariaLabel: "Report a problem with this order",
+            description: "Raise a dispute on an order for support to investigate.",
+            kind: "primary",
+        },
     },
     TESTER: {
         "save-note": {