@mohasinac/appkit 4.62.0 → 4.63.0

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

@@ -1,5 +1,10 @@
+import { normalizeError } from "../../../../errors/normalize.js";
 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 +36,66 @@ 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", normalizeError(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/reservationExpiry.d.ts

@@ -0,0 +1,17 @@
+import type { JobContext } from "../runtime/types";
+/**
+ * Return expired stock holds to the shelf.
+ *
+ * 🛑 This sweep is the ONLY thing that bounds a leaked hold. Everything else
+ * that ends a reservation is an action somebody takes — a release, a
+ * consume — and the entire reason `expiresAt` exists is that nobody takes
+ * those when they close the tab. Without this job a hold is permanent, and a
+ * permanent hold is indistinguishable from stock the seller no longer has.
+ *
+ * 🛑 Runs every 15 minutes, which is the real resolution of a TTL. The
+ * default hold is 72 hours, so the cadence does not need to be tight — but a
+ * daily sweep would make the worst case "expires at 09:01, returns tomorrow",
+ * and a buyer told an item is sold out for 24 hours after it stopped being
+ * held is the failure this exists to prevent.
+ */
+export declare function runReservationExpiry(ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,40 @@
+import { expireDueReservations } from "../../features/inventory/reservations.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/**
+ * Return expired stock holds to the shelf.
+ *
+ * 🛑 This sweep is the ONLY thing that bounds a leaked hold. Everything else
+ * that ends a reservation is an action somebody takes — a release, a
+ * consume — and the entire reason `expiresAt` exists is that nobody takes
+ * those when they close the tab. Without this job a hold is permanent, and a
+ * permanent hold is indistinguishable from stock the seller no longer has.
+ *
+ * 🛑 Runs every 15 minutes, which is the real resolution of a TTL. The
+ * default hold is 72 hours, so the cadence does not need to be tight — but a
+ * daily sweep would make the worst case "expires at 09:01, returns tomorrow",
+ * and a buyer told an item is sold out for 24 hours after it stopped being
+ * held is the failure this exists to prevent.
+ */
+export async function runReservationExpiry(ctx) {
+    ctx.logger.info("Starting stock-reservation expiry sweep");
+    let result;
+    try {
+        result = await expireDueReservations();
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        ctx.logger.error("Reservation expiry sweep failed", { message: normalized.message });
+        throw err;
+    }
+    /*
+     * `truncated` is logged rather than swallowed, and is the signal that the
+     * bound was reached: a run that hits its cap left real holds in place, and
+     * reading "expired 200" as "all done" is the same mistake a truncated
+     * recount invites (Root Cause #102).
+     */
+    ctx.logger.info("Reservation expiry sweep complete", {
+        scanned: result.scanned,
+        expired: result.expired,
+        truncated: result.truncated,
+    });
+}

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();
@@ -33,8 +33,21 @@ export async function runWeeklyPayoutEligibility(ctx) {
         holdSource: hold.source,
         cutoff: cutoff.toISOString(),
     });
+    /*
+     * 🛑 Resolved BEFORE the sweep, not per group.
+     *
+     * The widened query needs the whole set up front — the grouping by store
+     * happens after the rows come back, so a per-group lookup would arrive too
+     * late to have admitted the shipped rows in the first place. One bounded
+     * read against a hand-granted flag.
+     */
+    const trustedStoreIds = await storeRepository.findTrustedStoreIds();
+    if (trustedStoreIds.size > 0) {
+        ctx.logger.info(`${trustedStoreIds.size} trusted store(s) — their SHIPPED orders are eligible without waiting for delivery`, { trustedStoreCount: trustedStoreIds.size });
+    }
     const eligible = await orderRepository.getEligibleAutomatic(cutoff, {
         onWarn: (m, meta) => ctx.logger.warn(m, meta),
+        trustedStoreIds,
     });
     if (eligible.length === 0) {
         ctx.logger.info("No eligible delivered orders found");
@@ -75,7 +88,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
@@ -85,6 +106,8 @@ export async function runWeeklyPayoutEligibility(ctx) {
          */
         const sellerPlain = userRepository.revealUser(seller);
         const payoutInput = {
+            /* Every row this job writes settles a SELLER liability. */
+            payeeType: "store",
             storeId,
             // `displayName` is plaintext by D1; the email fallback must be revealed.
             sellerName: (seller.displayName ?? sellerPlain.email ?? store.ownerId),

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -9,6 +9,7 @@
  */
 export { couponExpiryHandler } from "./couponExpiry";
 export { offerExpiryHandler } from "./offerExpiry";
+export { reservationExpiryHandler } from "./reservationExpiry";
 export { cartPruneHandler } from "./cartPrune";
 export { notificationPruneHandler } from "./notificationPrune";
 export { dailyDataCleanupHandler } from "./dailyDataCleanup";

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

@@ -9,6 +9,7 @@
  */
 export { couponExpiryHandler } from "./couponExpiry.js";
 export { offerExpiryHandler } from "./offerExpiry.js";
+export { reservationExpiryHandler } from "./reservationExpiry.js";
 export { cartPruneHandler } from "./cartPrune.js";
 export { notificationPruneHandler } from "./notificationPrune.js";
 export { dailyDataCleanupHandler } from "./dailyDataCleanup.js";

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/jobs/handlers/reservationExpiry.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const reservationExpiryHandler: ScheduleHandler;

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

@@ -0,0 +1,2 @@
+import { runReservationExpiry } from "../core/reservationExpiry.js";
+export const reservationExpiryHandler = runReservationExpiry;

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.d.ts

@@ -29,7 +29,7 @@ import type { IconKey } from "../../../ui/icons/icon-registry";
 /** What KIND of action — drives default UI affordance (link vs button vs danger). */
 export type ActionKind = "primary" | "secondary" | "danger" | "ghost" | "link" | "chip";
 /** Resource bucket — keyed top-level in the ACTIONS tree. */
-export type ActionResource = "PRODUCT" | "AUCTION" | "PRE_ORDER" | "PRIZE_DRAW" | "DIGITAL_CODE" | "BUNDLE" | "GROUP" | "CATEGORY" | "BRAND" | "PART" | "BEY" | "FAQ" | "SUBLISTING" | "STORE" | "BLOG" | "EVENT" | "REVIEW" | "SHIPMENT" | "CATALOGUE" | "USER" | "SELLER" | "ADMIN" | "CART" | "CHECKOUT" | "NAV" | "MEDIA" | "SUPPORT" | "LOTTERY" | "TESTER";
+export type ActionResource = "PRODUCT" | "AUCTION" | "PRE_ORDER" | "PRIZE_DRAW" | "DIGITAL_CODE" | "BUNDLE" | "GROUP" | "CATEGORY" | "BRAND" | "ADS" | "PART" | "BEY" | "FAQ" | "SUBLISTING" | "STORE" | "BLOG" | "EVENT" | "REVIEW" | "SHIPMENT" | "CATALOGUE" | "USER" | "SELLER" | "ADMIN" | "CART" | "CHECKOUT" | "NAV" | "MEDIA" | "SUPPORT" | "LOTTERY" | "TESTER";
 /** Confirmation modal config — when set, <Button action={...}> opens
  *  a confirm dialog before firing the actual handler. */
 export interface ActionConfirmation {