@mohasinac/appkit 4.45.0 → 4.47.0

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

@@ -0,0 +1,70 @@
+/**
+ * categoryTaxonomyBackfill — re-derive a moved or renamed category's subtree.
+ *
+ * ── 🛑 THE GAP THIS CLOSES, measured 2026-10-13 ────────────────────────────
+ *
+ * A category RENAME did nothing at all. `PUT /api/admin/categories/[id]` calls
+ * `categoriesRepository.update(id, fields)` and stops, so after renaming a node:
+ *
+ *   - every product under it keeps the old `categoryNames`, and that array is
+ *     what `buildProductSearchTxt` tokenises — so the listing stops being
+ *     findable by its own category's NEW name and stays findable by the old
+ *     one. Both halves are wrong and neither errors;
+ *   - every DESCENDANT category keeps the old name inside its `ancestors[]`,
+ *     and `buildCategorySearchTxt` indexes those deliberately ("typing burst
+ *     reaches category-lost-longinus because Beyblade Burst is one of its
+ *     ancestors") — so the subtree's own search breaks too.
+ *
+ * A REPARENT was already half-handled: `moveCategory` -> `reparentSubtree` ->
+ * `rewriteProductChains` does re-derive the chains. 🛑 But it runs UNBOUNDED and
+ * SYNCHRONOUSLY inside the request — one `.get()` over every product in the
+ * subtree plus batched writes, against a 10s route ceiling (Rule #6) — and it
+ * nets `metrics.*` only, never `categoryCounts`. So the LIVE count was stale
+ * until the nightly recount while the grid was already correct, which produces
+ * the worst symptom of the pair: a page reading "54 listings" above an empty
+ * grid. A disagreement between two surfaces is worse than either being wrong.
+ *
+ * ── Why a JOB and not the trigger body ────────────────────────────────────
+ *
+ * Reparenting `category-beyblade-burst` touches hundreds of products. A trigger
+ * is at-least-once, and `FieldValue.increment` is atomic but NOT idempotent —
+ * which is exactly why counting lives in the repository rather than in a
+ * trigger (Root Cause #92's neighbourhood).
+ *
+ * 🛑 A RE-DERIVE, by contrast, IS idempotent: it is a pure function of the live
+ * tree, so running it twice writes the same values and the second run performs
+ * zero writes. That property is the whole licence for a trigger to start it.
+ *
+ * ── 🛑 THE ISR COST, stated rather than discovered ────────────────────────
+ *
+ * Every product write fires `onProductWrite` -> `notifyRevalidate`, and this
+ * project was paused with ISR writes at 3.1M against a 200K cap (15.5x). A
+ * rename of one tier-2 node could therefore drop hundreds of ISR entries.
+ * `productCacheFieldsChanged` already exists as the gate for exactly this
+ * question, and `categoryNames` IS a cache field — a renamed category must
+ * reach the rendered card, so the revalidation is correct rather than wasteful.
+ * What would be wasteful is revalidating when only the ancestor IDS moved, which
+ * no card renders; that case writes `categorySlugs` and nothing else.
+ *
+ * EXPORTS: runCategoryTaxonomyBackfill, CategoryTaxonomyBackfillPayload
+ *
+ * @tag domain:categories
+ * @tag layer:job
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:JOB_RUNNERS via onJobCreated
+ * @tag sideEffects:rewrites products.categorySlugs/categoryNames/searchTxt and categories.ancestors/searchTxt
+ */
+import type { JobContext } from "../runtime/types";
+import type { JobRunResult } from "./jobRunners";
+export interface CategoryTaxonomyBackfillPayload {
+    /** The node that moved or was renamed. */
+    categoryId: string;
+    /**
+     * What changed. Both re-derive the product closure; only `"rename"` also
+     * rewrites the subtree's own `ancestors[]`, because only a rename changes a
+     * name a descendant has cached.
+     */
+    kind: "rename" | "reparent";
+}
+export declare function runCategoryTaxonomyBackfill(payload: CategoryTaxonomyBackfillPayload, ctx: JobContext): Promise<JobRunResult>;

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

@@ -0,0 +1,302 @@
+/**
+ * categoryTaxonomyBackfill — re-derive a moved or renamed category's subtree.
+ *
+ * ── 🛑 THE GAP THIS CLOSES, measured 2026-10-13 ────────────────────────────
+ *
+ * A category RENAME did nothing at all. `PUT /api/admin/categories/[id]` calls
+ * `categoriesRepository.update(id, fields)` and stops, so after renaming a node:
+ *
+ *   - every product under it keeps the old `categoryNames`, and that array is
+ *     what `buildProductSearchTxt` tokenises — so the listing stops being
+ *     findable by its own category's NEW name and stays findable by the old
+ *     one. Both halves are wrong and neither errors;
+ *   - every DESCENDANT category keeps the old name inside its `ancestors[]`,
+ *     and `buildCategorySearchTxt` indexes those deliberately ("typing burst
+ *     reaches category-lost-longinus because Beyblade Burst is one of its
+ *     ancestors") — so the subtree's own search breaks too.
+ *
+ * A REPARENT was already half-handled: `moveCategory` -> `reparentSubtree` ->
+ * `rewriteProductChains` does re-derive the chains. 🛑 But it runs UNBOUNDED and
+ * SYNCHRONOUSLY inside the request — one `.get()` over every product in the
+ * subtree plus batched writes, against a 10s route ceiling (Rule #6) — and it
+ * nets `metrics.*` only, never `categoryCounts`. So the LIVE count was stale
+ * until the nightly recount while the grid was already correct, which produces
+ * the worst symptom of the pair: a page reading "54 listings" above an empty
+ * grid. A disagreement between two surfaces is worse than either being wrong.
+ *
+ * ── Why a JOB and not the trigger body ────────────────────────────────────
+ *
+ * Reparenting `category-beyblade-burst` touches hundreds of products. A trigger
+ * is at-least-once, and `FieldValue.increment` is atomic but NOT idempotent —
+ * which is exactly why counting lives in the repository rather than in a
+ * trigger (Root Cause #92's neighbourhood).
+ *
+ * 🛑 A RE-DERIVE, by contrast, IS idempotent: it is a pure function of the live
+ * tree, so running it twice writes the same values and the second run performs
+ * zero writes. That property is the whole licence for a trigger to start it.
+ *
+ * ── 🛑 THE ISR COST, stated rather than discovered ────────────────────────
+ *
+ * Every product write fires `onProductWrite` -> `notifyRevalidate`, and this
+ * project was paused with ISR writes at 3.1M against a 200K cap (15.5x). A
+ * rename of one tier-2 node could therefore drop hundreds of ISR entries.
+ * `productCacheFieldsChanged` already exists as the gate for exactly this
+ * question, and `categoryNames` IS a cache field — a renamed category must
+ * reach the rendered card, so the revalidation is correct rather than wasteful.
+ * What would be wasteful is revalidating when only the ancestor IDS moved, which
+ * no card renders; that case writes `categorySlugs` and nothing else.
+ *
+ * EXPORTS: runCategoryTaxonomyBackfill, CategoryTaxonomyBackfillPayload
+ *
+ * @tag domain:categories
+ * @tag layer:job
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:JOB_RUNNERS via onJobCreated
+ * @tag sideEffects:rewrites products.categorySlugs/categoryNames/searchTxt and categories.ancestors/searchTxt
+ */
+import { categoriesRepository } from "../../../../features/categories/repository/categories.repository.js";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore.js";
+import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
+import { buildProductSearchTxt } from "../../../../utils/search-txt-builders.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/** Firestore caps a batched write at 500 operations. */
+const BATCH_LIMIT = 400;
+/**
+ * One page of products per read.
+ *
+ * 🛑 A bound is the point of this job existing — `rewriteProductChains` has
+ * none, which is what makes it unsafe inside a request. Paged by document id so
+ * the cursor needs no index.
+ */
+const PAGE_SIZE = 200;
+/**
+ * A hard ceiling on how much one run will touch.
+ *
+ * Saturating it is REPORTED and the run stops rather than silently truncating:
+ * a half-backfilled subtree is a set of products that disagree with their own
+ * tree, and `countersReconcile`'s `drifted` is the signal that says so. The
+ * alternative — carrying on unbounded — is what the 540s function budget
+ * cannot promise.
+ */
+const MAX_PRODUCTS = 20000;
+/**
+ * Commit one page of product rewrites, chunked at Firestore's batch limit.
+ *
+ * Extracted because inline it reached brace-depth 6 and `audit-code-quality`
+ * refuses that — correctly: the loop over a page, the chunking, and the
+ * per-chunk failure handling are three separate concerns that read better apart.
+ *
+ * 🛑 A failed chunk is recorded per ROW rather than aborting the run. The rest
+ * of the subtree is still worth fixing, and a partially-backfilled subtree is
+ * exactly what `countersReconcile` reports as drift — so the failure is visible
+ * either way, and stopping would make it larger.
+ */
+async function commitProductWrites(ctx, categoryId, writes, succeeded, failed) {
+    for (let i = 0; i < writes.length; i += BATCH_LIMIT) {
+        const chunk = writes.slice(i, i + BATCH_LIMIT);
+        const batch = ctx.db.batch();
+        for (const w of chunk) {
+            batch.update(ctx.db.collection(PRODUCT_COLLECTION).doc(w.id), {
+                ...w.data,
+                updatedAt: new Date(),
+            });
+        }
+        try {
+            await batch.commit();
+            succeeded.push(...chunk.map((w) => w.id));
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            for (const w of chunk)
+                failed.push({ id: w.id, reason: e.message });
+            ctx.logger.error("categoryTaxonomyBackfill: batch failed", err, { categoryId });
+        }
+    }
+}
+export async function runCategoryTaxonomyBackfill(payload, ctx) {
+    const { categoryId, kind } = payload;
+    const empty = {
+        summary: { total: 0, succeeded: 0, skipped: 0, failed: 0 },
+        succeeded: [],
+        skipped: [],
+        failed: [],
+    };
+    if (!categoryId) {
+        return {
+            ...empty,
+            failed: [{ id: "-", reason: "categoryId is required" }],
+            summary: { total: 0, succeeded: 0, skipped: 0, failed: 1 },
+        };
+    }
+    const moved = await categoriesRepository.findById(categoryId);
+    if (!moved) {
+        /*
+         * Deleted between the write and this run. Not a fault: the delete route
+         * cascades products to the parent itself, so there is nothing here to fix.
+         */
+        ctx.logger.warn("categoryTaxonomyBackfill: category not found", { categoryId });
+        return { ...empty, skipped: [categoryId], summary: { total: 0, succeeded: 0, skipped: 1, failed: 0 } };
+    }
+    /*
+     * The whole subtree, in one read. `getDescendants` is a single
+     * `array-contains` over `parentIds` — which holds the FULL ancestor chain —
+     * so depth costs nothing extra.
+     */
+    const descendants = await categoriesRepository.getDescendants(categoryId);
+    const subtree = new Map([moved, ...descendants].map((c) => [c.id, c]));
+    const succeeded = [];
+    const skipped = [];
+    const failed = [];
+    /* ── 1. the subtree's own `ancestors[]`, on a rename only ──────────────── */
+    if (kind === "rename") {
+        try {
+            const refreshed = await categoriesRepository.refreshSubtreeAncestors(categoryId);
+            succeeded.push(...refreshed.map((id) => `category:${id}`));
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            failed.push({ id: `category:${categoryId}`, reason: e.message });
+            ctx.logger.error("categoryTaxonomyBackfill: ancestor refresh failed", err, { categoryId });
+        }
+    }
+    /* ── 2. every product whose closure contains the moved node ────────────── */
+    let scanned = 0;
+    let cursor = null;
+    let truncated = false;
+    for (;;) {
+        let q = ctx.db
+            .collection(PRODUCT_COLLECTION)
+            .where(PRODUCT_FIELDS.CATEGORY_SLUGS, "array-contains", categoryId)
+            .orderBy("__name__")
+            .limit(PAGE_SIZE);
+        if (cursor)
+            q = q.startAfter(cursor);
+        const page = await q.get();
+        if (page.empty)
+            break;
+        const writes = [];
+        for (const doc of page.docs) {
+            scanned += 1;
+            if (scanned > MAX_PRODUCTS) {
+                truncated = true;
+                break;
+            }
+            const data = doc.data();
+            /*
+             * Read the ASSIGNED list the same way every other consumer does —
+             * `categoryIds`, then the closure head, then the scalar. A different
+             * selection here would re-derive a chain from a leaf nothing else
+             * considers the leaf.
+             */
+            const assignments = Array.isArray(data.categoryIds) && data.categoryIds.length > 0
+                ? data.categoryIds
+                : [((Array.isArray(data.categorySlugs) && data.categorySlugs[0]) || data.category || "")].filter(Boolean);
+            /*
+             * 🛑 Resolve each assignment against the LIVE tree, falling back to the
+             * subtree map we already hold. An assignment OUTSIDE the moved subtree is
+             * unaffected by the move but still contributes its chain to the closure,
+             * so it has to be resolved too — dropping it would shorten the closure
+             * and un-list the product from a category it is genuinely in.
+             */
+            const resolved = [];
+            let unresolved = false;
+            for (const id of assignments) {
+                const cat = subtree.get(id) ?? (await categoriesRepository.findById(id));
+                if (!cat) {
+                    unresolved = true;
+                    continue;
+                }
+                resolved.push({
+                    id,
+                    parentIds: cat.parentIds ?? [],
+                    name: cat.name,
+                    ancestorNames: (cat.ancestors ?? []).map((a) => a?.name ?? ""),
+                });
+            }
+            if (resolved.length === 0) {
+                // Never blank a chain we cannot improve on.
+                skipped.push(doc.id);
+                continue;
+            }
+            /*
+             * The default is the DEEPEST assignment, and the tie-break is deliberately
+             * NOT consulted here: reading counts per product would be one extra read
+             * per row on a job that already pages thousands. A tie therefore falls to
+             * the stored order, which is the order `deriveTaxonomy` already chose —
+             * so a backfill never REORDERS a product's closure, it only repairs the
+             * ids and names inside it.
+             */
+            const deepest = resolved.reduce((best, c) => {
+                const tier = (subtree.get(c.id)?.tier ?? -1);
+                const bestTier = (subtree.get(best.id)?.tier ?? -1);
+                return tier > bestTier ? c : best;
+            }, resolved[0]);
+            const ordered = [deepest, ...resolved.filter((c) => c.id !== deepest.id)];
+            const categorySlugs = [];
+            const seen = new Set();
+            for (const c of ordered) {
+                for (const id of [c.id, ...c.parentIds.slice().reverse()]) {
+                    if (!id || seen.has(id))
+                        continue;
+                    seen.add(id);
+                    categorySlugs.push(id);
+                }
+            }
+            const categoryNames = [deepest.name, ...deepest.ancestorNames.slice().reverse()].filter((n) => !!n);
+            const slugsSame = (data.categorySlugs ?? []).join(">") === categorySlugs.join(">");
+            const namesSame = (data.categoryNames ?? []).join(">") === categoryNames.join(">");
+            if (slugsSame && namesSame) {
+                // Idempotent: a synced row costs no write. This is what makes an
+                // at-least-once trigger safe to start the job.
+                skipped.push(doc.id);
+                continue;
+            }
+            /*
+             * 🛑 `searchTxt` is rebuilt whenever the NAMES moved, and that is the half
+             * the reparent path never did. `buildProductSearchTxt` tokenises
+             * `categoryNames`, so a rename that stopped there would leave every
+             * product in the subtree findable by the old name and not the new one.
+             */
+            const next = { categorySlugs, categoryNames };
+            if (!namesSame) {
+                next.searchTxt = buildProductSearchTxt({ ...data, categoryNames });
+            }
+            writes.push({ id: doc.id, data: next });
+        }
+        if (writes.length > 0) {
+            await commitProductWrites(ctx, categoryId, writes, succeeded, failed);
+        }
+        if (truncated)
+            break;
+        cursor = page.docs[page.docs.length - 1] ?? null;
+        if (page.size < PAGE_SIZE)
+            break;
+    }
+    if (truncated) {
+        failed.push({
+            id: categoryId,
+            reason: `Stopped at the ${MAX_PRODUCTS}-product ceiling. The rest of the subtree still carries a stale chain — re-run, and expect countersReconcile to report drift.`,
+        });
+    }
+    ctx.logger.info("categoryTaxonomyBackfill: complete", {
+        categoryId,
+        kind,
+        subtreeSize: subtree.size,
+        productsScanned: scanned,
+        productsWritten: succeeded.filter((id) => !id.startsWith("category:")).length,
+        productsSkipped: skipped.length,
+        truncated,
+    });
+    return {
+        summary: {
+            total: succeeded.length + skipped.length + failed.length,
+            succeeded: succeeded.length,
+            skipped: skipped.length,
+            failed: failed.length,
+        },
+        succeeded,
+        skipped,
+        failed,
+    };
+}

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

@@ -2,6 +2,7 @@ import { normalizeError } from "../../../../errors/normalize.js";
 import { categoriesRepository, reviewRepository, storeRepository, } from "../../../../repositories/index.js";
 import { ProductStatusValues, PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore.js";
 import { CATEGORIES_COLLECTION } from "../../../../features/categories/schemas/firestore.js";
+import { CATEGORY_COUNTS_COLLECTION } from "../../../../features/categories/schemas/category-counts.js";
 import { ORDER_FIELDS, PRODUCT_FIELDS } from "../../../../constants/field-names.js";
 import { isListingRowAvailable } from "../../../shared/listing-types/_registry.js";
 import { QUERY_LIMIT } from "../handlers/messages.js";
@@ -14,22 +15,36 @@ const emptyTally = () => ({
     auctionIds: [],
     totalProducts: 0,
     totalAuctions: 0,
+    own: {},
+    total: {},
+    lotsOwn: 0,
+    lotsTotal: 0,
 });
 /** Filed DIRECTLY under this row — `metrics.productCount` / `auctionCount`. */
-function countOwn(t, productId, isAuction) {
+function countOwn(t, productId, isAuction, listingType, isLot) {
     if (isAuction)
         t.auctionIds.push(productId);
     else
         t.productIds.push(productId);
+    // G3b: lots are counted SEPARATELY from singles, which is what lets a leaf's
+    // own count mean one thing wherever a lot is filed.
+    if (isLot)
+        t.lotsOwn++;
+    else
+        t.own[listingType] = (t.own[listingType] ?? 0) + 1;
 }
 /** This row or any ancestor — `metrics.totalProductCount` / `totalAuctionCount`. */
-function countRollup(t, isAuction) {
+function countRollup(t, isAuction, listingType, isLot) {
     if (!t)
         return;
     if (isAuction)
         t.totalAuctions++;
     else
         t.totalProducts++;
+    if (isLot)
+        t.lotsTotal++;
+    else
+        t.total[listingType] = (t.total[listingType] ?? 0) + 1;
 }
 /**
  * Fold one published product into the tallies.
@@ -41,6 +56,11 @@ function countRollup(t, isAuction) {
  */
 function tallyProduct(productId, data, tallies, parentsOf) {
     const isAuction = data.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION;
+    // G3b. Default to "standard" for a row written before `listingType` was
+    // required — the same default `describeCountable` applies, so the nightly
+    // and the incremental value land on the same key rather than on two.
+    const listingType = data.listingType || "standard";
+    const isLot = data.isLot === true;
     /*
      * Count only what a visitor can actually see. A published-but-sold, ended,
      * closed or code-depleted row is excluded here for the same reason the listing
@@ -48,29 +68,59 @@ function tallyProduct(productId, data, tallies, parentsOf) {
      */
     if (!isListingRowAvailable(data, new Date()))
         return false;
-    // `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;
+    /*
+     * I3 — the ASSIGNED categories. `categoryIds` first, falling back to the old
+     * single-leaf selection for every row written before I1 added the field.
+     *
+     * 🛑 This selection must stay byte-identical to `describeCountable`'s. Two
+     * different ones drift silently, and the drift is invisible in the worst
+     * possible way: this job RECOUNTS FROM SCRATCH and overwrites, so it would
+     * "correct" a count the live trigger had right.
+     */
+    const owns = Array.isArray(data.categoryIds) && data.categoryIds.length > 0
+        ? data.categoryIds.filter(Boolean)
+        : [((Array.isArray(data.categorySlugs) && data.categorySlugs[0]) || data.category || "")].filter(Boolean);
     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);
+    /*
+     * ✅ Ancestors come from `parentsOf` — the LIVE tree, seeded from every
+     * category document — and NOT from the product's stored closure. Do not
+     * "simplify" that: it is what makes a reparent self-heal overnight. A version
+     * reading the stored chain would agree with a stale one, and then the drift
+     * this job exists to catch would be undetectable by it.
+     *
+     * 🛑 `own` bumps at EVERY assignment; `total` bumps once per distinct id
+     * across all their chains. Without the dedupe, two assignments sharing an
+     * ancestor would roll that ancestor up twice for one listing — which under
+     * one-per-root cannot happen, but this job reads whatever is in Firestore
+     * rather than whatever the write path allowed.
+     */
+    const rolledUp = new Set();
+    for (const own of owns) {
+        if (!tallies.has(own)) {
+            unknown = true;
+            continue;
+        }
+        countOwn(tallies.get(own), productId, isAuction, listingType, isLot);
+        for (const id of [own, ...(parentsOf.get(own) ?? [])]) {
+            if (rolledUp.has(id))
+                continue;
+            rolledUp.add(id);
+            countRollup(tallies.get(id), isAuction, listingType, isLot);
         }
     }
     // 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);
+    // 🛑 ...and never on the same row the chain already counted. If a leaf id were
+    // also a brand id, `countOwn` would fire twice for one listing. Today's
+    // `category-` / `brand-` prefixes make it impossible, which is precisely why
+    // it is guarded rather than trusted — the prefixes are a convention and this
+    // is an arithmetic invariant. Mirrors `describeCountable`'s own guard so the
+    // nightly and incremental values cannot disagree here.
+    const countedByChain = rolledUp;
+    if (data.brandSlug && !countedByChain.has(data.brandSlug) && tallies.has(data.brandSlug)) {
+        countOwn(tallies.get(data.brandSlug), productId, isAuction, listingType, isLot);
+        countRollup(tallies.get(data.brandSlug), isAuction, listingType, isLot);
     }
     return unknown;
 }
@@ -156,11 +206,66 @@ async function reconcileCategories(ctx) {
         if (page.size < PAGE_SIZE)
             break;
     }
+    /*
+     * G3b — the live `categoryCounts` documents, read so `drifted` stays an
+     * honest signal across BOTH stores of the count.
+     *
+     * 🛑 Read rather than blind-written. Writing only when `metrics` drifts would
+     * leave a counts document wrong forever in the narrow case where the
+     * product/auction aggregate happens to be right while a per-type split or a
+     * lot count is not — and that case is precisely what an incremental counter
+     * gets wrong, so it is the one the audit must see.
+     *
+     * One extra read per category row, once a night: 416 reads against a
+     * 50,000/day budget, under 1%.
+     */
+    const countsSnap = await ctx.db.collection(CATEGORY_COUNTS_COLLECTION).get();
+    const liveCounts = new Map();
+    for (const d of countsSnap.docs)
+        liveCounts.set(d.id, d.data());
+    /** Field-by-field, because a key present as 0 and a key absent are the same count. */
+    const sameMap = (a, b) => {
+        const keys = new Set([...Object.keys(a), ...Object.keys(b ?? {})]);
+        for (const k of keys)
+            if ((a[k] ?? 0) !== ((b ?? {})[k] ?? 0))
+                return false;
+        return true;
+    };
     let written = 0;
     let drifted = 0;
+    let countsWritten = 0;
     for (const doc of catSnap.docs) {
         const t = tallies.get(doc.id) ?? emptyTally();
         const m = doc.data().metrics ?? {};
+        const c = liveCounts.get(doc.id);
+        const countsSame = !!c &&
+            sameMap(t.own, c.own) &&
+            sameMap(t.total, c.total) &&
+            (c.lots?.own ?? 0) === t.lotsOwn &&
+            (c.lots?.total ?? 0) === t.lotsTotal;
+        if (!countsSame) {
+            try {
+                /*
+                 * 🛑 A FULL OVERWRITE, not a merge. The reconciler is the authority and
+                 * it enumerates the CATEGORIES rather than the products — which is what
+                 * lets a row whose last listing was deleted reset to zero. Root Cause
+                 * #102 is what a reconciler that could only ever add cost: 19 of 65
+                 * rows wrong, every one low.
+                 */
+                await ctx.db.collection(CATEGORY_COUNTS_COLLECTION).doc(doc.id).set({
+                    id: doc.id,
+                    own: t.own,
+                    total: t.total,
+                    lots: { own: t.lotsOwn, total: t.lotsTotal },
+                    updatedAt: new Date(),
+                });
+                countsWritten++;
+            }
+            catch (err) {
+                void normalizeError(err);
+                ctx.logger.error(`[categories] categoryCounts write failed for ${doc.id}`, err);
+            }
+        }
         const same = (m.productCount ?? 0) === t.productIds.length &&
             (m.auctionCount ?? 0) === t.auctionIds.length &&
             (m.totalProductCount ?? 0) === t.totalProducts &&
@@ -193,6 +298,10 @@ async function reconcileCategories(ctx) {
         publishedProductsScanned: scanned,
         drifted,
         written,
+        // G3b — a non-zero value here on a quiet day means the repository's
+        // incremental counter missed something. That is the whole reason the
+        // nightly pass survives an incremental model.
+        countsWritten,
         unknownCategory,
     });
 }

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

@@ -15,6 +15,7 @@ import { runWhatsAppNotify } from "./whatsappNotify.js";
 import { runNewsletterExport } from "./newsletterExport.js";
 import { runWhatsAppCatalogImport } from "./whatsappCatalogImport.js";
 import { runStoreNameBackfill } from "./storeNameBackfill.js";
+import { runCategoryTaxonomyBackfill } from "./categoryTaxonomyBackfill.js";
 async function runPayoutsWeeklyJob(_payload, ctx) {
     const { payoutsCreated, ordersProcessed, payoutIds } = await runWeeklyPayoutEligibility(ctx);
     return {
@@ -53,6 +54,16 @@ async function runWhatsAppCatalogImportJob(payload, ctx) {
 async function runStoreNameBackfillJob(payload, ctx) {
     return runStoreNameBackfill({ storeId: String(payload.storeId ?? "") }, ctx);
 }
+async function runCategoryTaxonomyBackfillJob(payload, ctx) {
+    /*
+     * `kind` is narrowed here rather than cast. An unrecognised value falls to
+     * "reparent", which is the SAFE default: it re-derives the product closure
+     * and skips the subtree ancestor refresh. The reverse default would run a
+     * subtree-wide write for a move that changed no name.
+     */
+    const kind = payload.kind === "rename" ? "rename" : "reparent";
+    return runCategoryTaxonomyBackfill({ categoryId: String(payload.categoryId ?? ""), kind }, ctx);
+}
 export const JOB_RUNNERS = {
     payoutsWeekly: runPayoutsWeeklyJob,
     hardBanCascade: runHardBanCascadeJob,
@@ -61,4 +72,5 @@ export const JOB_RUNNERS = {
     newsletterExport: runNewsletterExportJob,
     whatsappCatalogImport: runWhatsAppCatalogImportJob,
     storeNameBackfill: runStoreNameBackfillJob,
+    categoryTaxonomyBackfill: runCategoryTaxonomyBackfillJob,
 };