@mohasinac/appkit 4.43.0 → 4.44.0

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

@@ -0,0 +1,468 @@
+/**
+ * Core: evaluate the alert rules sellers and admins have configured — C3b.
+ *
+ * ## 🛑 The defect this closes: there was no evaluator at all
+ *
+ * `analyticsAlerts` had a schema, a seller CRUD UI, two API routes and four
+ * seeded fixtures — and **zero references across all 59 job files and
+ * `functions/`**. `lastTriggeredAt` was declared and written nowhere. So every
+ * alert a seller configured, and every one the seed created, could never fire.
+ *
+ * CLAUDE.md overstates this feature for exactly that reason: the parts that
+ * exist look complete, and the one that was missing is the one nothing points
+ * at. It also hid the metric-vocabulary split that C3a closed — two disjoint
+ * lists of metric names cannot be noticed while nothing reads the field.
+ *
+ * ## The switch is EXHAUSTIVE over `AlertMetric`
+ *
+ * `satisfies never` on the default branch, so adding a vocabulary member
+ * without an implementation does not compile. That is the mechanism behind the
+ * vocabulary's rule — *a metric is offerable only if the evaluator computes
+ * it* — rather than a convention someone has to remember.
+ *
+ * ## Read cost, and why it is bounded
+ *
+ * Metrics are computed ONCE PER OWNER, not once per alert: a seller with four
+ * alerts on orders pays for one orders query. Each query is bounded by
+ * `QUERY_LIMIT` and every count is reported as saturated when it hits the cap,
+ * because a count that silently stopped at 500 is a threshold comparison
+ * against a number that is not the number.
+ *
+ * 🛑 It does NOT scan per-product for `low_stock`. `availableQuantity <= N` is
+ * an inequality, and pairing one with an arbitrary sort is what demands an
+ * index nobody declares (Root Cause #59) — so the window is bounded and the
+ * predicate runs in memory, the same asymmetry § Availability describes.
+ */
+import { serverLogger } from "../../../../monitoring";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions";
+import { normalizeError } from "../../../../errors/normalize";
+import { ORDER_FIELDS, PAYOUT_FIELDS, PRODUCT_FIELDS, } from "../../../../constants/field-names";
+import { ProductStatusValues, PRODUCT_COLLECTION, } from "../../../../features/products/schemas/firestore";
+import { ALERT_METRICS, LOW_STOCK_THRESHOLD, } from "../../../../features/store-extensions/constants/alert-metrics";
+/** Bound on every count query. Reported when it saturates. */
+const QUERY_LIMIT = 500;
+/*
+ * Collection names and the two field names that have no entry in
+ * `constants/field-names.ts`.
+ *
+ * Declared here rather than inlined at the call site because
+ * `audit-registry-constants` is right about the general rule — a hand-typed
+ * field name in a query clause is how a rename passes a typecheck and returns
+ * zero rows. These two (`reports.status`, `analyticsAlerts.isActive`) belong
+ * in the shared registry the day a second reader appears; one local constant
+ * is the honest intermediate rather than adding a registry entry nothing else
+ * uses.
+ */
+const ORDERS_COLLECTION = "orders";
+const REVIEWS_COLLECTION = "reviews";
+const PAYOUTS_COLLECTION = "payouts";
+const REPORTS_COLLECTION = "reports";
+const USERS_COLLECTION = "users";
+const REPORT_STATUS_FIELD = "status";
+const ANALYTICS_ALERT_IS_ACTIVE_FIELD = "isActive";
+/**
+ * An alert that is still true must not re-notify every run.
+ *
+ * Without this a seller with five products below five units gets a mail every
+ * hour until they restock — and the first thing anyone does with a channel
+ * that cries wolf is mute it, which costs the alerts that matter.
+ */
+const RENOTIFY_COOLDOWN_HOURS = 24;
+/** Compare, with the operator the alert carries. */
+export function alertFires(value, operator, threshold) {
+    switch (operator) {
+        case ">":
+            return value > threshold;
+        case "<":
+            return value < threshold;
+        case ">=":
+            return value >= threshold;
+        case "<=":
+            return value <= threshold;
+        case "==":
+            return value === threshold;
+        case "!=":
+            return value !== threshold;
+        default: {
+            /*
+             * Exhaustive. A seventh operator would not compile rather than silently
+             * never firing — which is the failure mode of a `default: return false`
+             * and is how an alert can look configured and be inert.
+             */
+            const unreachable = operator;
+            return unreachable;
+        }
+    }
+}
+/**
+ * Whether enough time has passed to notify again.
+ *
+ * An alert that has NEVER fired always notifies — absence of
+ * `lastTriggeredAt` means "not yet", never "recently".
+ */
+export function mayRenotify(alert, now) {
+    if (!alert.lastTriggeredAt)
+        return true;
+    const last = new Date(alert.lastTriggeredAt).getTime();
+    if (Number.isNaN(last))
+        return true;
+    return now.getTime() - last >= RENOTIFY_COOLDOWN_HOURS * 60 * 60 * 1000;
+}
+/**
+ * 🛑 GOODS VALUE of a completed order, never `totalPrice`.
+ *
+ * C0 established that the grand total folds in GST, the platform fee,
+ * shipping and add-ons — and an alert reporting a seller's revenue as the
+ * buyer's grand total tells them they earned money we collected on somebody
+ * else's behalf. This is the same base a payout is computed from.
+ *
+ * An unpaid or refunded order contributes **zero**: delivered-then-refunded
+ * has a realised value of nothing, which is the same rule `priceIndexRollup`
+ * applies to the index.
+ *
+ * Extracted because `audit-code-quality` flagged the inline version at
+ * brace-depth 6 and it was right — "for each order, if paid, if not refunded,
+ * for each item, if live" is four questions in one block.
+ */
+function completedOrderGoodsValue(order) {
+    if (order.paymentStatus !== "paid")
+        return 0;
+    if (order.refunds && order.refunds.length > 0)
+        return 0;
+    return (order.items ?? []).reduce((sum, it) => {
+        const live = (it.quantity ?? 0) - (it.cancelledQuantity ?? 0);
+        return live > 0 ? sum + live * (it.unitPrice ?? 0) : sum;
+    }, 0);
+}
+function buildMetricCache(ctx, bucket, now, onSaturated) {
+    const cache = new Map();
+    const since = (windowHours) => new Date(now.getTime() - windowHours * 60 * 60 * 1000);
+    /** A bounded count, flagged when it hits the cap. */
+    const boundedCount = async (build) => {
+        const snap = await build().limit(QUERY_LIMIT).get();
+        return { value: snap.size, saturated: snap.size >= QUERY_LIMIT };
+    };
+    function buildQuery() {
+        return ctx.db.collection(PRODUCT_COLLECTION);
+    }
+    /** Seller metrics scope to the store; admin metrics span the platform. */
+    const storeScoped = (q) => bucket.scope === "seller" ? q.where(PRODUCT_FIELDS.STORE_ID, "==", bucket.ownerId) : q;
+    const compute = async (metric, windowHours) => {
+        switch (metric) {
+            case "low_stock": {
+                /*
+                 * Bounded fetch + in-memory predicate, never `availableQuantity <= N`
+                 * in the query. An inequality pushed alongside any other clause
+                 * demands a composite index in an order nobody declares, and the
+                 * failure mode is `FAILED_PRECONDITION` swallowed into a zero —
+                 * i.e. an alert that silently never fires (Root Cause #59).
+                 */
+                const snap = await storeScoped(ctx.db.collection(PRODUCT_COLLECTION).where(PRODUCT_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED))
+                    .limit(QUERY_LIMIT)
+                    .get();
+                if (snap.size >= QUERY_LIMIT)
+                    onSaturated(metric);
+                return snap.docs.filter((d) => {
+                    const q = d.data().availableQuantity ?? 0;
+                    return q > 0 && q <= LOW_STOCK_THRESHOLD;
+                }).length;
+            }
+            case "out_of_stock": {
+                const snap = await storeScoped(ctx.db.collection(PRODUCT_COLLECTION).where(PRODUCT_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED))
+                    .limit(QUERY_LIMIT)
+                    .get();
+                if (snap.size >= QUERY_LIMIT)
+                    onSaturated(metric);
+                return snap.docs.filter((d) => (d.data().availableQuantity ?? 0) <= 0).length;
+            }
+            case "orders_count": {
+                const r = await boundedCount(() => storeScoped(ctx.db.collection(ORDERS_COLLECTION).where(ORDER_FIELDS.CREATED_AT, ">=", since(windowHours))));
+                if (r.saturated)
+                    onSaturated(metric);
+                return r.value;
+            }
+            case "cancelled_orders": {
+                const r = await boundedCount(() => storeScoped(ctx.db
+                    .collection("orders")
+                    .where(ORDER_FIELDS.STATUS, "==", ORDER_FIELDS.STATUS_VALUES.CANCELLED)
+                    .where(ORDER_FIELDS.CREATED_AT, ">=", since(windowHours))));
+                if (r.saturated)
+                    onSaturated(metric);
+                return r.value;
+            }
+            case "revenue_total": {
+                const snap = await storeScoped(ctx.db
+                    .collection("orders")
+                    .where(ORDER_FIELDS.STATUS, "==", ORDER_FIELDS.STATUS_VALUES.DELIVERED)
+                    .where(ORDER_FIELDS.CREATED_AT, ">=", since(windowHours)))
+                    .limit(QUERY_LIMIT)
+                    .get();
+                if (snap.size >= QUERY_LIMIT)
+                    onSaturated(metric);
+                /*
+                 * 🛑 GOODS VALUE, not `totalPrice`. C0 established that the grand
+                 * total folds in GST, the platform fee, shipping and add-ons — and an
+                 * alert that reports a seller's revenue as the buyer's grand total
+                 * tells them they earned money we collected on somebody else's
+                 * behalf. Same base the payout is computed from.
+                 */
+                const total = snap.docs.reduce((sum, d) => sum + completedOrderGoodsValue(d.data()), 0);
+                return Math.round(total * 100) / 100;
+            }
+            case "pending_payout_total": {
+                const snap = await (bucket.scope === "seller"
+                    ? ctx.db.collection(PAYOUTS_COLLECTION).where(PRODUCT_FIELDS.STORE_ID, "==", bucket.ownerId)
+                    : ctx.db.collection(PAYOUTS_COLLECTION))
+                    .where(PAYOUT_FIELDS.STATUS, "in", ["PENDING", "PROCESSING"])
+                    .limit(QUERY_LIMIT)
+                    .get();
+                if (snap.size >= QUERY_LIMIT)
+                    onSaturated(metric);
+                let total = 0;
+                for (const d of snap.docs)
+                    total += d.data().amount ?? 0;
+                return Math.round(total * 100) / 100;
+            }
+            case "avg_rating": {
+                const snap = await ctx.db
+                    .collection("reviews")
+                    .where(PRODUCT_FIELDS.STORE_ID, "==", bucket.ownerId)
+                    .limit(QUERY_LIMIT)
+                    .get();
+                if (snap.size >= QUERY_LIMIT)
+                    onSaturated(metric);
+                const ratings = snap.docs
+                    .map((d) => d.data().rating)
+                    .filter((r) => typeof r === "number");
+                /*
+                 * 🛑 No reviews returns 0, and 0 would FIRE a `< 4` alert — telling a
+                 * brand-new store its rating has collapsed when it has no rating at
+                 * all. `NaN` instead, which every comparison answers false to, so the
+                 * alert stays quiet until there is something to judge.
+                 */
+                if (ratings.length === 0)
+                    return Number.NaN;
+                return Math.round((ratings.reduce((a, b) => a + b, 0) / ratings.length) * 100) / 100;
+            }
+            case "reviews_count": {
+                const r = await boundedCount(() => ctx.db
+                    .collection("reviews")
+                    .where(PRODUCT_FIELDS.STORE_ID, "==", bucket.ownerId)
+                    .where(ORDER_FIELDS.CREATED_AT, ">=", since(windowHours)));
+                if (r.saturated)
+                    onSaturated(metric);
+                return r.value;
+            }
+            case "open_reports": {
+                const r = await boundedCount(() => ctx.db.collection(REPORTS_COLLECTION).where(REPORT_STATUS_FIELD, "==", "pending"));
+                if (r.saturated)
+                    onSaturated(metric);
+                return r.value;
+            }
+            case "pending_moderation": {
+                const r = await boundedCount(() => ctx.db.collection(PRODUCT_COLLECTION).where(PRODUCT_FIELDS.STATUS, "==", "in_review"));
+                if (r.saturated)
+                    onSaturated(metric);
+                return r.value;
+            }
+            default: {
+                /*
+                 * 🛑 Exhaustive over `AlertMetric`. A vocabulary member with no
+                 * implementation does NOT compile — which is what makes the
+                 * vocabulary's rule ("offerable only if computable") a mechanism
+                 * rather than a note. The original feature had the opposite: seven
+                 * offerable metrics, none computable.
+                 */
+                const unreachable = metric;
+                return unreachable;
+            }
+        }
+    };
+    return {
+        get(metric, windowHours) {
+            /*
+             * Keyed on metric AND window, because two alerts on `orders_count` with
+             * 24h and 48h windows are genuinely two different numbers. Keying on the
+             * metric alone would serve one alert the other's answer.
+             */
+            const key = `${metric}:${windowHours}`;
+            let p = cache.get(key);
+            if (!p) {
+                p = compute(metric, windowHours);
+                cache.set(key, p);
+            }
+            return p;
+        },
+    };
+}
+/**
+ * The owner's contact details, resolved once per owner.
+ *
+ * 🛑 This is how the seller's `notifyChannels` is HONOURED rather than
+ * ignored. `sendNotification` decides email and WhatsApp eligibility itself
+ * (type gate → admin allow-list → user prefs → daily budget) and takes no
+ * channel list — but it cannot email an address it was not given. So omitting
+ * `userEmail` when the seller did not tick email is a real narrowing through
+ * the existing gate, with no second channel-routing mechanism invented beside
+ * it.
+ *
+ * The in-app row is always written, which matches the UI: "in-app" is the
+ * default channel and there is no way to turn the bell off.
+ */
+async function resolveOwnerContact(ctx, bucket) {
+    /*
+     * A seller alert's `ownerId` is the OWNER'S UID (the seed writes
+     * `user-tyson-blader`), not the store slug — unlike the metric queries
+     * above, which scope on `storeId`. Those are two different identifiers and
+     * conflating them is Root Cause #98's shape, so they are read from two
+     * different places on purpose.
+     */
+    const snap = await ctx.db.collection(USERS_COLLECTION).doc(bucket.ownerId).get();
+    if (!snap.exists)
+        return {};
+    const u = snap.data();
+    return {
+        ...(u.email ? { email: u.email } : {}),
+        ...(u.phoneNumber ? { phone: u.phoneNumber } : {}),
+    };
+}
+export async function runAnalyticsAlertEvaluate(ctx) {
+    const now = new Date();
+    const snap = await ctx.db
+        .collection("analyticsAlerts")
+        .where(ANALYTICS_ALERT_IS_ACTIVE_FIELD, "==", true)
+        .limit(QUERY_LIMIT)
+        .get();
+    if (snap.size >= QUERY_LIMIT) {
+        ctx.logger.warn("analyticsAlertEvaluate: alert scan saturated — some alerts were not evaluated", {
+            limit: QUERY_LIMIT,
+        });
+    }
+    /* Group by owner so each metric is computed once, not once per alert. */
+    const buckets = new Map();
+    for (const d of snap.docs) {
+        const alert = { id: d.id, ...d.data() };
+        if (!alert.ownerId || !ALERT_METRICS[alert.metric]) {
+            /*
+             * A stored metric outside the vocabulary. Logged rather than skipped
+             * silently: these are the pre-C3a rows, and the only other way to see
+             * one is that the seller's list renders a raw token with no description.
+             */
+            serverLogger.warn("analyticsAlertEvaluate: alert carries an unknown metric", {
+                alertId: d.id,
+                metric: alert.metric,
+            });
+            continue;
+        }
+        const key = `${alert.scope}:${alert.ownerId}`;
+        const bucket = buckets.get(key) ?? { scope: alert.scope, ownerId: alert.ownerId, alerts: [] };
+        bucket.alerts.push(alert);
+        buckets.set(key, bucket);
+    }
+    let evaluated = 0;
+    let fired = 0;
+    let suppressed = 0;
+    let errored = 0;
+    for (const bucket of buckets.values()) {
+        const saturatedMetrics = new Set();
+        const cache = buildMetricCache(ctx, bucket, now, (m) => saturatedMetrics.add(m));
+        /** One read per owner, and only when something actually fires. */
+        let contact = null;
+        const notifyOwner = async (b, alert, value) => {
+            contact ?? (contact = await resolveOwnerContact(ctx, b));
+            const def = ALERT_METRICS[alert.metric];
+            await sendNotification({
+                /*
+                 * `system`, deliberately, rather than a new `analytics_alert` type.
+                 *
+                 * A new type touches five maps and — more to the point — would need an
+                 * `EMAIL_ELIGIBLE_TYPES` answer. Against a 100/day Resend ceiling, an
+                 * email-eligible type driven by a user-configurable threshold is the
+                 * fastest way to exhaust the allowance. `system` is already eligible
+                 * and already carries operational messages, which is what this is.
+                 */
+                type: "system",
+                userId: b.ownerId,
+                title: alert.label || def.label,
+                priority: "normal",
+                message: `${def.label} is ${value} (${alert.operator} ${alert.threshold} over the last ${alert.windowHours}h). ${def.describes}`,
+                ...(alert.notifyChannels?.includes("email") && contact.email
+                    ? { userEmail: contact.email }
+                    : {}),
+                ...(alert.notifyChannels?.includes("whatsapp") && contact.phone
+                    ? { userPhone: contact.phone }
+                    : {}),
+                audience: b.scope === "admin" ? "admin" : "seller",
+            });
+        };
+        for (const alert of bucket.alerts) {
+            try {
+                const value = await cache.get(alert.metric, alert.windowHours ?? 24);
+                evaluated += 1;
+                /*
+                 * 🛑 A SATURATED count must not fire. The real number is at least the
+                 * cap, so a `<` comparison against it is meaningless and a `>` one is
+                 * true for the wrong reason. Reporting "we could not measure this" is
+                 * the honest outcome — the same rule as `truncated` rendering "50+"
+                 * rather than a false total.
+                 */
+                if (saturatedMetrics.has(alert.metric)) {
+                    suppressed += 1;
+                    ctx.logger.warn("analyticsAlertEvaluate: skipped on a saturated metric", {
+                        alertId: alert.id,
+                        metric: alert.metric,
+                    });
+                    continue;
+                }
+                if (Number.isNaN(value)) {
+                    suppressed += 1;
+                    continue;
+                }
+                if (!alertFires(value, alert.operator, alert.threshold))
+                    continue;
+                if (!mayRenotify(alert, now)) {
+                    suppressed += 1;
+                    continue;
+                }
+                /*
+                 * The write happens FIRST, before the notification.
+                 *
+                 * If the notification throws, the cooldown has still been recorded —
+                 * so a persistently failing channel cannot turn into one attempt per
+                 * run forever. The inverse order would retry a broken WhatsApp send
+                 * every hour against a 100/day email allowance.
+                 */
+                await ctx.db
+                    .collection("analyticsAlerts")
+                    .doc(alert.id)
+                    .update({ lastTriggeredAt: now, lastObservedValue: value, updatedAt: now });
+                fired += 1;
+                await notifyOwner(bucket, alert, value);
+                ctx.logger.info("analyticsAlertEvaluate: alert fired", {
+                    alertId: alert.id,
+                    ownerId: alert.ownerId,
+                    metric: alert.metric,
+                    value,
+                    operator: alert.operator,
+                    threshold: alert.threshold,
+                });
+            }
+            catch (err) {
+                const e = normalizeError(err);
+                errored += 1;
+                ctx.logger.error("analyticsAlertEvaluate: alert evaluation failed", {
+                    alertId: alert.id,
+                    metric: alert.metric,
+                    message: e.message,
+                });
+            }
+        }
+    }
+    ctx.logger.info("analyticsAlertEvaluate: complete", {
+        owners: buckets.size,
+        evaluated,
+        fired,
+        suppressed,
+        errored,
+    });
+}

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

@@ -1,6 +1,7 @@
 import { orderRepository, payoutRepository, storeRepository, userRepository, siteSettingsRepository, } from "../../../../repositories";
 import { getDefaultCurrency } from "../../../../core/index";
 import { computePayoutDeduction } from "../../../shared/fees/calculator";
+import { ordersTaxableValue } from "../../../shared/checkout/order-math";
 import { BATCH_LIMIT } from "../handlers/messages";
 const AUTO_PAYOUT_WINDOW_DAYS = 7;
 function getBusinessDayCutoff(daysAgo) {
@@ -48,7 +49,19 @@ export async function runAutoPayoutEligibility(ctx) {
             continue;
         }
         const sellerId = store.ownerId;
-        const grossAmount = orders.reduce((sum, o) => sum + (o.data.totalPrice ?? 0), 0);
+        /*
+         * The TAXABLE VALUE — see `orderTaxableValue`. Two narrowings, both
+         * needed, and the variable keeps the name `grossAmount` only because
+         * `PayoutDocument.grossAmount` does:
+         *
+         *  1. not `totalPrice`, the grand total, which folds in GST, the platform
+         *     fee the buyer already paid, shipping, COD handling, add-ons and the
+         *     EMI surcharge — so it paid out our GST, took the fee twice, and
+         *     computed every percentage on an inflated base;
+         *  2. not the gross goods value either, because prices are tax-INCLUSIVE,
+         *     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 payoutInput = {
             storeId,

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

@@ -203,22 +203,38 @@ async function reconcileStores(ctx) {
     let errors = 0;
     for (const storeId of storeIds) {
         try {
-            const storeSnap = await ctx.db.collection(STORES_COLLECTION).doc(storeId).get();
-            if (!storeSnap.exists)
-                continue;
-            const sellerId = storeSnap.data().ownerId;
-            if (!sellerId)
-                continue;
+            /*
+             * 🛑 `storeId`, NOT a `sellerId` resolved from `ownerId`. Every store on
+             * the platform has been getting 0 products and 0 delivered orders
+             * written to its stats, nightly, in silence.
+             *
+             * Two compounding defects were here. The field `sellerId` **exists on
+             * neither `ProductDocument` nor `OrderDocument`** — measured, zero
+             * occurrences in either schema; both carry `storeId`. And the value was
+             * `store.ownerId`, which is the Auth UID, while `storeId` IS the store
+             * slug (§ Store Identity Architecture). So the query named a field no
+             * document has, with a value from the wrong namespace.
+             *
+             * Firestore answers an equality on a missing field with ZERO rows and
+             * raises nothing, so `setStats(storeId, 0, 0, …)` wrote confident zeros
+             * over whatever the live triggers had computed. That is Root Cause
+             * #100's family: a reader whose field no document carries returns
+             * nothing and reads as "this store has sold nothing".
+             *
+             * The store document read is gone with it — the loop already holds the
+             * id it needed, so resolving `ownerId` was a read per store spent on
+             * getting the answer wrong.
+             */
             const [productsSnap, ordersSnap, reviewStats] = await Promise.all([
                 ctx.db
                     .collection(PRODUCT_COLLECTION)
-                    .where(ORDER_FIELDS.SELLER_ID, "==", sellerId)
+                    .where(PRODUCT_FIELDS.STORE_ID, "==", storeId)
                     .where(ORDER_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED)
                     .limit(QUERY_LIMIT)
                     .get(),
                 ctx.db
                     .collection(ORDERS_COLLECTION)
-                    .where(ORDER_FIELDS.SELLER_ID, "==", sellerId)
+                    .where(ORDER_FIELDS.STORE_ID, "==", storeId)
                     .where(ORDER_FIELDS.STATUS, "==", ORDER_FIELDS.STATUS_VALUES.DELIVERED)
                     .limit(QUERY_LIMIT)
                     .get(),

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

@@ -38,6 +38,12 @@ import { normalizeError } from "../../../../errors/normalize";
  * itself, and each of those writes spawns a no-op invocation. A full reseed of the
  * 58-category forest therefore costs on the order of thousands of invocations, all
  * of them terminating. That is a cost worth knowing before a reseed, not a runaway.
+ *
+ * 🛑 AND THAT COST IS QUADRATIC, which is why the CREATE branch now has a
+ * precomputed-coordinates escape hatch (see the block at the top of `isCreate`).
+ * ~n²/4 writes: 58 nodes ≈ 840, 330 ≈ 27,000, 1,500 ≈ 560,000 — the last two
+ * being 1.4x and 28x the 20k/day Firestore write budget. A seed that already
+ * carries correct DFS coordinates skips the branch entirely.
  */
 import { FieldValue } from "firebase-admin/firestore";
 import { BATCH_LIMIT } from "../handlers/messages";
@@ -97,6 +103,54 @@ export async function handleCategoryWrite(input, ctx) {
     const isUpdate = !!before && !!after;
     try {
         if (isCreate) {
+            /*
+             * 🛑 BULK-WRITE ESCAPE HATCH — skip everything when the writer already
+             * computed valid DFS coordinates.
+             *
+             * The branch below is O(n) reads + O(n) writes PER CATEGORY CREATED:
+             * `shiftPositions` runs an unbounded `where("position", ">=", t)` and
+             * rewrites every row it returns, because a new node is inserted as its
+             * parent's FIRST child and everything after it moves. Averaged over a
+             * build that is ~n/2 rows shifted per insert, so seeding N categories
+             * costs Σ(i/2) ≈ n²/4 writes:
+             *
+             *     58 nodes  ->    ~840 writes   (tolerable, and what we pay today)
+             *    330 nodes  -> ~27,000 writes   (above the 20k/day Firestore budget)
+             *  1,500 nodes  -> ~560,000 writes  (28x the daily budget, in one run)
+             *
+             * `buildCategoryTree` already computes `position` and `subtreeSize` as
+             * a correct global DFS pre-order — the exact numbering this handler
+             * would otherwise recompute one insert at a time. Worse than wasteful:
+             * the CREATE branch OVERWRITES that work with `subtreeSize: 1` and a
+             * locally-derived position, leaving the collection wrong until the
+             * nightly reconcile repairs it.
+             *
+             * So a document that arrives already numbered is left alone.
+             *
+             * The test is `position >= 1`, which is unambiguous because BOTH
+             * writers of a precomputed position are 1-based: `buildCategoryTree`
+             * and `positionsReconcile`. A category created through the admin/store
+             * routes carries `position: 0` (the `createWithHierarchy` default) and
+             * therefore still gets the full treatment.
+             *
+             * 🛑 This is NOT the Root Cause #92 shape. It is not a value-equality
+             * guard on a field this handler writes — it is a precondition on the
+             * INCOMING document, and the handler takes no action at all when it
+             * holds. There is nothing to compare and nothing to re-trigger.
+             */
+            const precomputedPosition = after.position;
+            const precomputedSubtree = after.subtreeSize;
+            if (typeof precomputedPosition === "number" &&
+                precomputedPosition >= 1 &&
+                typeof precomputedSubtree === "number" &&
+                precomputedSubtree >= 1) {
+                ctx.logger.info("Category created with precomputed DFS coords — skipping position assignment", {
+                    categoryId,
+                    position: precomputedPosition,
+                    subtreeSize: precomputedSubtree,
+                });
+                return;
+            }
             const parentIds = after.parentIds ?? [];
             const parentId = parentIds.length > 0 ? parentIds[parentIds.length - 1] : null;
             let insertPosition;

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

@@ -0,0 +1,47 @@
+/**
+ * Core: the realised-price index — what things actually SOLD for here.
+ *
+ * ## Why this exists
+ *
+ * Every price signal we show a seller today is an ASK: the seeded `market`
+ * band is a competitor's listed price, and a competitor's sold-out row proves
+ * the item is GONE, not that it sold at that figure. With 76–93% of listings
+ * across the crawled catalogues never selling, the gap between an ask and a
+ * realised price is the single most useful thing we can tell a seller — and we
+ * are the only party who can measure it on our own sales.
+ *
+ * A seeded blog post already tells sellers to *"check what similar items sold
+ * for on LetItRip in the last 30 days"*, which has never been possible.
+ *
+ * ## 🛑 `market` and `sold` are NEVER blended
+ *
+ * They answer different questions and the gap IS the information. Averaging
+ * them would launder an inference into a measurement. This job writes only the
+ * sold half, into its own collection, and never touches the seeded band.
+ *
+ * ## The authoritative field
+ *
+ * **`OrderDocument.items[].unitPrice`** — and specifically not:
+ *
+ *   `OrderDocument.unitPrice`  the FIRST line's price (`unitPriceFor(items[0])`),
+ *                              wrong for every other line
+ *   `OrderDocument.totalPrice` folds in GST, platform fee, shipping and add-ons
+ *   `BidDocument.status==won`  its own comment: `orderId` is absent on a
+ *                              won-but-unpaid bid
+ *   `OfferDocument==accepted`  an agreement, not a sale. `paid` is the sale
+ *   `product.currentBid`       a display mirror a pending buyout never writes
+ *
+ * Won auctions and accepted offers arrive through the same field via
+ * `lockedPrice`, so one field covers all six acquisition paths and
+ * `sourceContext` labels each for free.
+ *
+ * ## Why daily and never live
+ *
+ * A live index would scan orders per request — the unbounded-per-request
+ * pattern that paused this project on Hobby caps. One pre-computed read per
+ * row, with a visible "prices as of {date}". Deliberately one day stale.
+ */
+import type { JobContext } from "../runtime/types";
+/** How far back a band looks. */
+export declare const PRICE_INDEX_WINDOW_DAYS = 90;
+export declare function runPriceIndexRollup(ctx: JobContext): Promise<void>;