@mohasinac/appkit 4.37.1 → 4.39.0

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

@@ -1,10 +1,18 @@
 import { normalizeError } from "../../../../errors/normalize";
 import { getAdminAuth, getAdminRealtimeDb } from "../../../../providers/db-firebase";
+import { RTDB_PATHS } from "../../../../providers/db-firebase/rtdb-paths";
 import { jobsRepository } from "../../../../repositories";
 import { batchDelete } from "../handlers/_helpers";
 const AUTH_STALE_MS = 3 * 60 * 1000;
 const PAYMENT_STALE_MS = 15 * 60 * 1000;
 const BULK_STALE_MS = 15 * 60 * 1000;
+/**
+ * Longer than the other three on purpose: a tester batch can take ten minutes
+ * between triggering a send and asserting on it, and a ping deleted mid-batch
+ * would read as "no email was sent" — the exact false negative these records
+ * exist to prevent.
+ */
+const EMAIL_STALE_MS = 60 * 60 * 1000;
 const JOBS_TTL_DAYS = 30;
 export async function runCleanupRtdbEvents(ctx) {
     ctx.logger.info("Starting RTDB events cleanup");
@@ -68,6 +76,38 @@ export async function runCleanupRtdbEvents(ctx) {
         void normalizeError(bulkErr);
         ctx.logger.error("Bulk events cleanup failed (non-fatal)", bulkErr);
     }
+    /*
+     * Tester email pings. Written only for the harness mailbox (see
+     * `send-recorder.ts`), so this is normally a no-op — but an unpruned RTDB
+     * channel is precisely the thing that quietly accumulates, and the Firebase
+     * budget notes `auction-bids/*` as the one family with no TTL. Do not make it
+     * the second.
+     *
+     * The Firestore row is the record and is NOT touched here; this only clears the
+     * ping.
+     */
+    try {
+        const emailSnap = await rtdb.ref(RTDB_PATHS.EMAIL_EVENTS).get();
+        if (emailSnap.exists()) {
+            const allEmailEvents = emailSnap.val();
+            const staleEmailIds = Object.entries(allEmailEvents)
+                .filter(([, node]) => {
+                const at = node.at ? Date.parse(node.at) : 0;
+                // An unparseable or missing timestamp is stale by definition: it can
+                // never age out on its own, so leaving it would pin the node forever.
+                return !Number.isFinite(at) || at === 0 || at < now - EMAIL_STALE_MS;
+            })
+                .map(([id]) => id);
+            if (staleEmailIds.length > 0) {
+                await Promise.all(staleEmailIds.map((id) => rtdb.ref(`${RTDB_PATHS.EMAIL_EVENTS}/${id}`).remove()));
+                ctx.logger.info("Email event pings removed", { count: staleEmailIds.length });
+            }
+        }
+    }
+    catch (emailErr) {
+        void normalizeError(emailErr);
+        ctx.logger.error("Email events cleanup failed (non-fatal)", emailErr);
+    }
     try {
         const staleJobRefs = await jobsRepository.getStaleFinishedRefs(JOBS_TTL_DAYS);
         if (staleJobRefs.length > 0) {

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

@@ -1,57 +1,170 @@
 import { normalizeError } from "../../../../errors/normalize";
 import { categoriesRepository, reviewRepository, storeRepository, } from "../../../../repositories";
 import { ProductStatusValues, PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
+import { CATEGORIES_COLLECTION } from "../../../../features/categories/schemas/firestore";
 import { ORDER_FIELDS, PRODUCT_FIELDS } from "../../../../constants/field-names";
 import { QUERY_LIMIT } from "../handlers/messages";
 const STORES_COLLECTION = "stores";
 const ORDERS_COLLECTION = "orders";
+/** Page size for the products scan. Bounded reads, unbounded total coverage. */
+const PAGE_SIZE = 500;
+const emptyTally = () => ({
+    productIds: [],
+    auctionIds: [],
+    totalProducts: 0,
+    totalAuctions: 0,
+});
+/** Filed DIRECTLY under this row — `metrics.productCount` / `auctionCount`. */
+function countOwn(t, productId, isAuction) {
+    if (isAuction)
+        t.auctionIds.push(productId);
+    else
+        t.productIds.push(productId);
+}
+/** This row or any ancestor — `metrics.totalProductCount` / `totalAuctionCount`. */
+function countRollup(t, isAuction) {
+    if (!t)
+        return;
+    if (isAuction)
+        t.totalAuctions++;
+    else
+        t.totalProducts++;
+}
+/**
+ * Fold one published product into the tallies.
+ *
+ * A named function rather than an inner block: this is the only place the
+ * own-vs-rollup distinction is actually APPLIED, and burying it four levels deep
+ * inside a paginating loop is how it stopped being visible last time.
+ * Returns true when the product names a category nothing recognises.
+ */
+function tallyProduct(productId, data, tallies, parentsOf) {
+    const isAuction = data.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION;
+    // `category` is @deprecated in favour of `categorySlugs[]`; mirror the live
+    // trigger's selection exactly so the two agree (onProductWrite.ts).
+    const leaf = (Array.isArray(data.categorySlugs) && data.categorySlugs[0]) ||
+        data.category ||
+        null;
+    let unknown = false;
+    if (leaf && !tallies.has(leaf)) {
+        unknown = true;
+    }
+    else if (leaf) {
+        countOwn(tallies.get(leaf), productId, isAuction);
+        // Roll up through self + every ancestor. `parentIds` already holds the
+        // WHOLE chain, so this is one pass rather than a walk.
+        for (const id of [leaf, ...(parentsOf.get(leaf) ?? [])]) {
+            countRollup(tallies.get(id), isAuction);
+        }
+    }
+    // Brands are a flat dimension: a brand row has no product children of its own
+    // beyond what points at it, so own === total by construction — which is why
+    // it is counted on both axes at once.
+    if (data.brandSlug && tallies.has(data.brandSlug)) {
+        countOwn(tallies.get(data.brandSlug), productId, isAuction);
+        countRollup(tallies.get(data.brandSlug), isAuction);
+    }
+    return unknown;
+}
+/**
+ * Recount every category and brand row from the products collection.
+ *
+ * 🛑 THREE THINGS THIS HAS TO GET RIGHT, each of which the previous version
+ * got wrong, and none of which produced an error:
+ *
+ * 1. **Own vs rollup are different numbers.** `metrics.productCount` is what is
+ *    filed directly under a row; `metrics.totalProductCount` is that plus every
+ *    descendant. The old code passed one number for both — see `setMetrics`'s
+ *    header for the full account and the 19-of-65 measurement.
+ *
+ * 2. **Every row is written, including the ones that are now empty.** The old
+ *    code built its map from products that EXIST, so a category whose last item
+ *    was deleted was never visited and kept its stale count forever. Seeding
+ *    `tallies` from the category list instead of from the products is the whole
+ *    fix, and it is why the loop below walks `parentsOf` rather than `tallies`
+ *    entries.
+ *
+ * 3. **Brands are counted too.** Brands are `categoryType:"brand"` rows in this
+ *    same collection and `BrandDetailPageView` reads `metrics.productCount` off
+ *    them — but nothing has ever written it. They hang off `brandSlug`, not off
+ *    the category chain, so they get their own pass.
+ *
+ * Reads are bounded by pagination rather than by `.limit(QUERY_LIMIT)`, which
+ * silently recounted a subset the moment the catalogue passed 1,000 published
+ * rows — a truncated recount is indistinguishable from a correct one.
+ */
 async function reconcileCategories(ctx) {
-    const snap = await ctx.db
-        .collection(PRODUCT_COLLECTION)
-        .where(ORDER_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED)
-        .limit(QUERY_LIMIT)
-        .get();
-    ctx.logger.info(`[categories] ${snap.size} published products found`);
-    const leafCounts = {};
-    for (const doc of snap.docs) {
-        const data = doc.data();
-        // `category` is @deprecated in favor of `categorySlugs[]` — mirrors the
-        // same effective-category selection as onProductWrite.ts's live trigger
-        // so the nightly reconcile agrees with real-time updates instead of
-        // silently no-op'ing on products written via categorySlugs-only paths.
-        const catId = Array.isArray(data.categorySlugs) && data.categorySlugs.length > 0
-            ? data.categorySlugs[0]
-            : data.category;
-        if (!catId)
-            continue;
-        if (!leafCounts[catId])
-            leafCounts[catId] = { productIds: [], auctionIds: [] };
-        if (data.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION)
-            leafCounts[catId].auctionIds.push(doc.id);
-        else
-            leafCounts[catId].productIds.push(doc.id);
+    // Every category row, so rows that dropped to zero are still reset.
+    const catSnap = await ctx.db.collection(CATEGORIES_COLLECTION).get();
+    const parentsOf = new Map();
+    for (const d of catSnap.docs) {
+        parentsOf.set(d.id, d.data().parentIds ?? []);
     }
-    const ancestorAggregates = {};
-    let leafUpdated = 0;
-    for (const [catId, { productIds, auctionIds }] of Object.entries(leafCounts)) {
-        await categoriesRepository.setMetrics(catId, productIds.length, auctionIds.length, productIds, auctionIds);
-        leafUpdated++;
-        const parentIds = (await categoriesRepository.findById(catId))?.parentIds ?? [];
-        for (const ancestorId of parentIds) {
-            if (!ancestorAggregates[ancestorId]) {
-                ancestorAggregates[ancestorId] = { productDelta: 0, auctionDelta: 0 };
+    const tallies = new Map();
+    for (const id of parentsOf.keys())
+        tallies.set(id, emptyTally());
+    let scanned = 0;
+    let unknownCategory = 0;
+    let cursor = null;
+    for (;;) {
+        let q = ctx.db
+            .collection(PRODUCT_COLLECTION)
+            .where(ORDER_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED)
+            .orderBy("__name__")
+            .limit(PAGE_SIZE);
+        if (cursor)
+            q = q.startAfter(cursor);
+        const page = await q.get();
+        if (page.empty)
+            break;
+        for (const doc of page.docs) {
+            scanned++;
+            if (tallyProduct(doc.id, doc.data(), tallies, parentsOf)) {
+                unknownCategory++;
             }
-            ancestorAggregates[ancestorId].productDelta += productIds.length;
-            ancestorAggregates[ancestorId].auctionDelta += auctionIds.length;
         }
+        cursor = page.docs[page.docs.length - 1];
+        if (page.size < PAGE_SIZE)
+            break;
     }
-    const ancestorEntries = Object.entries(ancestorAggregates);
-    for (const [ancestorId, { productDelta, auctionDelta }] of ancestorEntries) {
-        await categoriesRepository.setMetrics(ancestorId, productDelta, auctionDelta, [], []);
+    let written = 0;
+    let drifted = 0;
+    for (const doc of catSnap.docs) {
+        const t = tallies.get(doc.id) ?? emptyTally();
+        const m = doc.data().metrics ?? {};
+        const same = (m.productCount ?? 0) === t.productIds.length &&
+            (m.auctionCount ?? 0) === t.auctionIds.length &&
+            (m.totalProductCount ?? 0) === t.totalProducts &&
+            (m.totalAuctionCount ?? 0) === t.totalAuctions;
+        // Skipping no-op writes keeps a 65-row nightly pass near-free against the
+        // 20k/day write budget — and makes `drifted` a real signal rather than a
+        // count of how many rows exist. A non-zero `drifted` on a quiet day means
+        // the live trigger missed something.
+        if (same)
+            continue;
+        drifted++;
+        try {
+            await categoriesRepository.setMetrics(doc.id, {
+                productCount: t.productIds.length,
+                auctionCount: t.auctionIds.length,
+                totalProductCount: t.totalProducts,
+                totalAuctionCount: t.totalAuctions,
+                productIds: t.productIds,
+                auctionIds: t.auctionIds,
+            });
+            written++;
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.error(`[categories] setMetrics failed for ${doc.id}`, err);
+        }
     }
     ctx.logger.info("[categories] reconciliation complete", {
-        leafCategoriesUpdated: leafUpdated,
-        ancestorCategoriesUpdated: ancestorEntries.length,
+        categoryRows: catSnap.size,
+        publishedProductsScanned: scanned,
+        drifted,
+        written,
+        unknownCategory,
     });
 }
 async function reconcileStores(ctx) {

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

@@ -4,6 +4,39 @@ import { normalizeError } from "../../../../errors/normalize";
  * CREATE → insert into parent's subtree + shift later siblings;
  * DELETE → shift back; MOVE → mark `positionDirty` so the nightly reconcile
  * job rebuilds.
+ *
+ * trigger-self-write-ok: terminates at depth 1 — the only branch that writes is
+ * gated on `parentIds` CHANGING, and none of this handler's own writes touch
+ * `parentIds`.
+ *
+ * 🛑 WHY THAT IS SAFE, SPELLED OUT — this is a `documentWritten` trigger on
+ * `categories` that writes back to `categories`, including to the triggering
+ * document (L110). That is the shape of Root Cause #92, which logged 1,017,548
+ * invocations in 24 hours, so it deserves an explicit argument rather than trust:
+ *
+ *   CREATE writes → sibling `position`s, own `position`/`subtreeSize`, ancestor
+ *                   `subtreeSize`. Every one re-enters as an UPDATE.
+ *   DELETE writes → sibling `position`s, ancestor `subtreeSize`. Same.
+ *   UPDATE        → writes ONLY when `beforeParent !== afterParent`. None of the
+ *                   writes above change `parentIds`, so the re-entry compares
+ *                   equal and does nothing. The cascade stops.
+ *   MOVE          → writes `positionDirty`, which is also not `parentIds`, so its
+ *                   own re-entry likewise does nothing. One extra hop, then stop.
+ *
+ * The guard is STRUCTURAL, not a value comparison — that is what makes it stronger
+ * than #92's. `onShipmentHeaderWrite` recomputed and rewrote the same derived field
+ * every time and relied on `JSON.stringify` equality to notice it had not changed;
+ * key-order sensitivity made that comparison always false, so it re-triggered
+ * forever. Here there is nothing to compare: the handler cannot write the field it
+ * branches on.
+ *
+ * 🛑 If you ever make this handler write `parentIds`, it becomes a true loop. Do
+ * not — a move is deliberately deferred to the nightly reconcile for this reason.
+ *
+ * Not free, though: creating one category writes to its siblings, its ancestors and
+ * 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.
  */
 import { FieldValue } from "firebase-admin/firestore";
 import { BATCH_LIMIT } from "../handlers/messages";

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

@@ -23,48 +23,102 @@ async function getParentIds(categoryId) {
         return [];
     return (await categoriesRepository.findById(categoryId))?.parentIds ?? [];
 }
+/**
+ * 🛑 THIS IS A CROSS-COLLECTION TRIGGER AND THAT IS THE SAFETY ARGUMENT.
+ *
+ * It watches `products` and writes to `categories`, so its own writes cannot
+ * re-trigger it — there is no termination condition to get right, because there
+ * is no cycle. Contrast `onCategoryWrite`, which DOES write its own collection
+ * and is safe only because of a structural guard on `parentIds`.
+ *
+ * **Do not move this counting into `onCategoryWrite`.** A `categories` trigger
+ * that increments a `categories` document is exactly the shape of Root Cause
+ * #92 — `onShipmentHeaderWrite` recursed 1,017,548 times in 24 hours against a
+ * 2M/month quota because a key-order-sensitive `JSON.stringify` guard could
+ * never return true, and the only symptom was a billing page.
+ *
+ * Brands ride along here rather than in a second trigger: a brand IS a
+ * `categoryType:"brand"` row in the same collection, so it is the same write to
+ * the same place, and splitting it would double the invocations for nothing.
+ * A brand has no ancestors, so it is staged with an empty parent chain and its
+ * own count equals its rollup by construction.
+ */
 async function dispatchProductWriteEvent(p) {
-    const { productId, beforeCategory, afterCategory, beforeStoreId, afterStoreId, isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx } = p;
-    if (isDelete && wasPublished && beforeCategory) {
-        const parentIds = await getParentIds(beforeCategory);
-        const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, beforeCategory, parentIds, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
+    const { productId, beforeCategory, afterCategory, beforeBrand, afterBrand, beforeStoreId, afterStoreId, isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx } = p;
+    /** Stage one category (and, if given, one brand) at `sign` × 1 item. */
+    const stage = (batch, categoryId, brandId, parentIds, auction, sign) => {
+        const productDelta = auction ? 0 : sign;
+        const auctionDelta = auction ? sign : 0;
+        if (categoryId) {
+            categoriesRepository.updateMetricsInBatch(batch, categoryId, parentIds, productDelta, auctionDelta, productId);
+        }
+        if (brandId) {
+            categoriesRepository.updateMetricsInBatch(batch, brandId, [], productDelta, auctionDelta, productId);
+        }
+    };
+    /*
+     * `batch.update()` REJECTS a missing document, and a batch is atomic — so one
+     * dangling ancestor id loses every increment in the batch, not just its own.
+     * That throw is caught by the caller and logged non-fatally, which is correct:
+     * a counter is not worth failing a product write over. What makes it
+     * acceptable is that `countersReconcile` now RECOUNTS FROM SCRATCH nightly and
+     * rewrites every row that disagrees, so a lost increment self-heals within a
+     * day and shows up as a non-zero `drifted` in that job's log.
+     */
+    const commit = async (batch, what, meta) => {
         await batch.commit();
+        ctx.logger.info(what, { productId, ...meta });
+    };
+    if (isDelete && wasPublished && (beforeCategory || beforeBrand)) {
+        const batch = ctx.db.batch();
+        stage(batch, beforeCategory, beforeBrand, await getParentIds(beforeCategory ?? ""), beforeIsAuction, -1);
+        await commit(batch, "Decremented counters on hard-delete", { category: beforeCategory, brand: beforeBrand, storeId: beforeStoreId });
         if (beforeStoreId)
             await storeRepository.incrementTotalProducts(beforeStoreId, -1);
-        ctx.logger.info("Decremented counters on hard-delete", { productId, category: beforeCategory, storeId: beforeStoreId });
         return;
     }
-    if (!wasPublished && isPublished && afterCategory) {
-        const parentIds = await getParentIds(afterCategory);
+    if (!wasPublished && isPublished && (afterCategory || afterBrand)) {
         const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, afterCategory, parentIds, isAuction ? 0 : 1, isAuction ? 1 : 0, productId);
-        await batch.commit();
+        stage(batch, afterCategory, afterBrand, await getParentIds(afterCategory ?? ""), isAuction, 1);
+        await commit(batch, "Incremented counters on publish", { category: afterCategory, brand: afterBrand, storeId: afterStoreId });
         if (afterStoreId)
             await storeRepository.incrementTotalProducts(afterStoreId, 1);
-        ctx.logger.info("Incremented counters on publish", { productId, category: afterCategory, storeId: afterStoreId });
         return;
     }
-    if (wasPublished && !isPublished && beforeCategory) {
-        const parentIds = await getParentIds(beforeCategory);
+    if (wasPublished && !isPublished && (beforeCategory || beforeBrand)) {
         const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, beforeCategory, parentIds, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
-        await batch.commit();
+        stage(batch, beforeCategory, beforeBrand, await getParentIds(beforeCategory ?? ""), beforeIsAuction, -1);
+        await commit(batch, "Decremented counters on unpublish", { category: beforeCategory, brand: beforeBrand, storeId: beforeStoreId });
         if (beforeStoreId)
             await storeRepository.incrementTotalProducts(beforeStoreId, -1);
-        ctx.logger.info("Decremented counters on unpublish", { productId, category: beforeCategory, storeId: beforeStoreId });
         return;
     }
-    if (wasPublished && isPublished && beforeCategory && afterCategory && beforeCategory !== afterCategory) {
+    /*
+     * Still published, but re-filed. This is the branch a naive trigger gets
+     * wrong — incrementing the new home without decrementing the old one is how
+     * a count drifts permanently upward with no event to blame it on. Category
+     * and brand are tested INDEPENDENTLY because either can move without the
+     * other: re-tagging the brand while the category stands still used to fall
+     * through every branch and silently leave both brand rows wrong.
+     */
+    if (wasPublished && isPublished) {
+        const categoryMoved = beforeCategory !== afterCategory;
+        const brandMoved = beforeBrand !== afterBrand;
+        if (!categoryMoved && !brandMoved)
+            return;
         const [beforeParents, afterParents] = await Promise.all([
-            getParentIds(beforeCategory),
-            getParentIds(afterCategory),
+            getParentIds(categoryMoved ? beforeCategory ?? "" : ""),
+            getParentIds(categoryMoved ? afterCategory ?? "" : ""),
         ]);
         const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, beforeCategory, beforeParents, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
-        categoriesRepository.updateMetricsInBatch(batch, afterCategory, afterParents, isAuction ? 0 : 1, isAuction ? 1 : 0, productId);
-        await batch.commit();
-        ctx.logger.info("Moved product between categories", { productId, from: beforeCategory, to: afterCategory });
+        stage(batch, categoryMoved ? beforeCategory : null, brandMoved ? beforeBrand : null, beforeParents, beforeIsAuction, -1);
+        stage(batch, categoryMoved ? afterCategory : null, brandMoved ? afterBrand : null, afterParents, isAuction, 1);
+        await commit(batch, "Re-filed product", {
+            fromCategory: categoryMoved ? beforeCategory : undefined,
+            toCategory: categoryMoved ? afterCategory : undefined,
+            fromBrand: brandMoved ? beforeBrand : undefined,
+            toBrand: brandMoved ? afterBrand : undefined,
+        });
     }
 }
 export async function handleProductWrite(input, ctx) {
@@ -77,6 +131,16 @@ export async function handleProductWrite(input, ctx) {
     // no-op category metrics here. Prefer categorySlugs[0], fall back to legacy category.
     const beforeCategory = getEffectiveCategory(before);
     const afterCategory = getEffectiveCategory(after);
+    /*
+     * `brandSlug` is the brand ROW's document id in this same `categories`
+     * collection. `brand` is the display NAME and is not a key — CLAUDE.md's
+     * § "Brand matching is by DISPLAY NAME" — so it must never be used here.
+     * Nothing had ever written a brand row's metrics, while
+     * BrandDetailPageView.tsx:124 reads `brand?.metrics?.productCount` — so every
+     * brand page fell through to its tab count or to a hard 0.
+     */
+    const beforeBrand = before?.brandSlug ?? null;
+    const afterBrand = after?.brandSlug ?? null;
     const beforeStoreId = (before?.storeId || before?.sellerId) ?? null;
     const afterStoreId = (after?.storeId || after?.sellerId) ?? null;
     const isAuction = after?.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION;
@@ -86,12 +150,16 @@ export async function handleProductWrite(input, ctx) {
     const isDelete = !after;
     try {
         await dispatchProductWriteEvent({
-            productId, beforeCategory, afterCategory, beforeStoreId, afterStoreId,
+            productId, beforeCategory, afterCategory, beforeBrand, afterBrand,
+            beforeStoreId, afterStoreId,
             isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx,
         });
     }
     catch (err) {
         void normalizeError(err);
-        ctx.logger.error("Counter update failed (non-fatal)", err, { productId });
+        // Non-fatal on purpose — a counter must never fail a product write. The
+        // healer is `countersReconcile`, which recounts from scratch nightly and
+        // reports how many rows it had to correct.
+        ctx.logger.error("Counter update failed (non-fatal — countersReconcile will heal it tonight)", err, { productId });
     }
 }

package/dist/_internal/server/notifications/send-recorder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Record what the mailer decided, so the tester can assert on it without an inbox.
+ *
+ * ## Why this exists
+ *
+ * 21 checklist cases are about email. Reading a real mailbox over IMAP can answer
+ * some of them, but it is the wrong instrument for most:
+ *
+ *   - **Six of them assert an email should NOT arrive** (kill switch spares staff,
+ *     opt-out honoured, no employee blast, losing bidders get no mail). Over IMAP,
+ *     "nothing arrived" is unprovable — you wait N seconds and hope, and a slow
+ *     inbox is indistinguishable from a working suppression. Here it is one read.
+ *   - Delivery latency makes every other case slow and flaky for no added truth:
+ *     whether Resend accepted the handoff says nothing about whether the app made
+ *     the right decision, which is what the cases are actually about.
+ *
+ * So this records the DECISION and its inputs. A real inbox is still the only
+ * proof of real delivery, and the two or three cases that assert that keep using
+ * one (`tester/scripts/lib/inbox.mjs`).
+ *
+ * ## Why here and not in `guardSend`
+ *
+ * `SendGuardContext` carries channel/feature/audience and deliberately no
+ * recipient — the guard's own docstring explains it must not become the transport.
+ * `sendEmail()` is the one place that holds the recipient, the rendered body AND
+ * the guard's verdict, which is exactly the tuple a case needs.
+ *
+ * ## 🛑 Gated, because recording real people's mail is a privacy problem
+ *
+ * Recording recipients and bodies for actual users would be a new PII store with
+ * no retention story. So this writes ONLY when the recipient is the harness
+ * mailbox (`TESTER_EMAIL_ID`), or when `EMAIL_RECORDER_ALL` is explicitly set for
+ * local debugging. Absent that env var, this function is a no-op and costs one
+ * string comparison.
+ *
+ * Best-effort throughout: a recorder that can fail a send is worse than no
+ * recorder, so every path swallows. Same discipline as `recordAdminAction`.
+ *
+ * @tag domain:notifications,tester
+ * @tag layer:server
+ * @tag access:server-only
+ */
+/** Firestore collection holding the canonical record. */
+export declare const EMAIL_EVENTS_COLLECTION = "emailEvents";
+export type EmailSendOutcome = "sent" | "suppressed" | "failed";
+export interface EmailSendRecord {
+    /** Recipient(s), as passed to the provider. */
+    to: string | string[];
+    subject: string;
+    /** `feature` from the guard — the notification type or named flow. */
+    feature: string;
+    audience: string;
+    channel: string;
+    outcome: EmailSendOutcome;
+    /** Suppression reason (`admin_disabled`, `daily_ceiling`, …) or the error text. */
+    reason?: string;
+    /**
+     * The rendered body. Recorded so a case can assert the email has a heading, a
+     * lead line and a button rather than one bare paragraph — an assertion that is
+     * otherwise only checkable by eye in a real client.
+     */
+    html?: string;
+}
+/**
+ * Should this send be recorded at all?
+ *
+ * Exported so the audit and tests can exercise the gate directly rather than
+ * inferring it from behaviour.
+ */
+export declare function shouldRecordSend(to: string | string[]): boolean;
+/**
+ * Write the record. Never throws, never blocks the send.
+ *
+ * Firestore is canonical and RTDB is only a ping — the same split the messaging
+ * feature already uses. The body does NOT go into RTDB: `bulk_events` is
+ * uncapped and a newsletter CSV already goes there, which is the mistake not to
+ * repeat on a channel that fires on every email.
+ */
+export declare function recordSendAttempt(record: EmailSendRecord): Promise<void>;