@mohasinac/appkit 4.39.1 → 4.40.0

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

@@ -92,6 +92,27 @@ function tallyProduct(productId, data, tallies, parentsOf) {
  * 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.
+ *
+ * 🛑 THIS IS THE ONLY RECOUNT. `appkit/scripts/backfill-category-metrics.mjs`
+ * was a second implementation of exactly this, reachable as
+ * `npm run categories:backfill-metrics`, and it was wrong four ways: it wrote the
+ * descendant rollup into `productCount` (the own count — Root Cause 102, the bug
+ * this file's own/rollup split exists to fix), blanked `productIds` on every
+ * ancestor, enumerated only categories that HAVE products so a row that dropped
+ * to zero kept its stale count, and — worst — wrote any row that was both a leaf
+ * with products AND an ancestor twice, the ancestor pass silently overwriting its
+ * own count. It was deleted 2026-09-14 rather than repaired: a second recount
+ * that disagrees with this one is a way to *introduce* drift while believing you
+ * are fixing it. If a manual run is ever needed, invoke this job — do not write
+ * another script.
+ *
+ * As of 2026-09-14 this is a BACKSTOP, not the maintainer. `onProductWrite`
+ * (products → categories) and `CategoriesRepository.reparentSubtree`
+ * (structural moves + deletes) keep the counters correct in real time; this pass
+ * exists because a `batch.update()` against a dangling ancestor id throws and
+ * loses every increment in that batch. A non-zero `drifted` in its log is
+ * therefore a real signal that one of those paths missed something — it is not
+ * routine.
  */
 async function reconcileCategories(ctx) {
     // Every category row, so rows that dropped to zero are still reset.

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

@@ -104,8 +104,42 @@ async function dispatchProductWriteEvent(p) {
     if (wasPublished && isPublished) {
         const categoryMoved = beforeCategory !== afterCategory;
         const brandMoved = beforeBrand !== afterBrand;
-        if (!categoryMoved && !brandMoved)
+        /*
+         * A listing can also change WHICH counter it belongs in without moving at
+         * all: flipping listingType between auction and anything else has to move
+         * the item from `auctionCount` to `productCount` on the same rows. That is
+         * tested independently for the same reason category and brand are — it
+         * happens on its own, and when it did, this branch returned early and left
+         * the item counted as an auction forever.
+         */
+        const typeChanged = beforeIsAuction !== isAuction;
+        if (!categoryMoved && !brandMoved && !typeChanged)
             return;
+        /*
+         * A pure type flip: nothing moved, so the item leaves one counter and joins
+         * the other on the SAME rows. Staged as ONE call carrying both deltas rather
+         * than a -1 followed by a +1, because those would be two writes to the same
+         * document in one batch. Note the two deltas cancel, so `totalItemCount`
+         * correctly does not move — the item did not come or go, it changed shape.
+         */
+        if (!categoryMoved && !brandMoved) {
+            const parents = await getParentIds(afterCategory ?? "");
+            const productDelta = isAuction ? -1 : 1;
+            const auctionDelta = isAuction ? 1 : -1;
+            const batch = ctx.db.batch();
+            if (afterCategory) {
+                categoriesRepository.updateMetricsInBatch(batch, afterCategory, parents, productDelta, auctionDelta, productId);
+            }
+            if (afterBrand) {
+                categoriesRepository.updateMetricsInBatch(batch, afterBrand, [], productDelta, auctionDelta, productId);
+            }
+            await commit(batch, "Listing type changed", {
+                productId,
+                from: beforeIsAuction ? "auction" : "product",
+                to: isAuction ? "auction" : "product",
+            });
+            return;
+        }
         const [beforeParents, afterParents] = await Promise.all([
             getParentIds(categoryMoved ? beforeCategory ?? "" : ""),
             getParentIds(categoryMoved ? afterCategory ?? "" : ""),

package/dist/features/categories/components/CategoryDetailPageView.js

@@ -57,10 +57,18 @@ export async function CategoryDetailPageView({ slug }) {
                 .listByType("bundle", { activeOnly: true, limit: 50 })
                 .then(hidePublicTestData), { route: "/categories/[slug]", key: "category.bundles", fallback: [] })
             : Promise.resolve([]),
+        /*
+         * Every DESCENDANT, not just the direct children this used to fetch. A
+         * four-tier tree showed only tier+1 here, so the whole lower half of the
+         * catalogue was unreachable from the page that is supposed to be its index —
+         * you had to already know a sub-sub-category existed to navigate to it.
+         * `getDescendants` is one array-contains query over `parentIds`, which holds
+         * the full ancestor chain, so depth costs nothing extra.
+         */
         category?.id
-            ? safeRead(() => categoriesRepository.getChildren(category.id), {
+            ? safeRead(() => categoriesRepository.getDescendants(category.id), {
                 route: "/categories/[slug]",
-                key: "category.children",
+                key: "category.descendants",
                 fallback: [],
             })
             : Promise.resolve([]),
@@ -153,7 +161,11 @@ export async function CategoryDetailPageView({ slug }) {
     const preOrderCount = counts["pre-orders"] ?? 0;
     const coverImage = category?.display?.coverImage;
     const hasCover = Boolean(coverImage);
-    return (_jsxs(Main, { children: [_jsxs(Section, { className: `relative ${__O.hidden} ${hasCover ? "min-h-[220px] md:min-h-[280px]" : "bg-[var(--appkit-color-bg)]"}`, children: [hasCover && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "absolute inset-0", children: _jsx(MediaImage, { src: coverImage, alt: "", size: "banner" }) }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" })] })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsxs(Nav, { layout: "flex", gap: "2xs", textSize: "sm", className: "mb-4", "aria-label": "Breadcrumb", children: [_jsx(Link, { href: String(ROUTES.HOME), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Home" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORIES), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Categories" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Span, { weight: "medium", className: hasCover ? "text-white" : "text-[var(--appkit-color-text)]", children: category?.name ?? slug })] }), _jsx(Heading, { color: "inverse", level: 1, className: `mb-2 ${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: category?.name ?? slug }), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mb-4 ${hasCover ? "/80" : ""}`, size: "base", children: category.description })), _jsxs(Row, { wrap: true, gap: "sm", children: [productCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: "inverse", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "bg-primary/10 text-primary-700 dark:text-primary-400", rounded: "full", padding: "pill-sm-tall", children: [productCount.toLocaleString(), " ", productCount === 1 ? "product" : "products"] })), auctionCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "warning", surface: hasCover ? undefined : "warning-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [auctionCount.toLocaleString(), " ", auctionCount === 1 ? "auction" : "auctions"] })), preOrderCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "info", surface: hasCover ? undefined : "info-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [preOrderCount.toLocaleString(), " ", preOrderCount === 1 ? "pre-order" : "pre-orders"] })), storeCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "success", surface: hasCover ? undefined : "success-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [storeCount.toLocaleString(), " ", storeCount === 1 ? "store" : "stores"] }))] })] })] }), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), childCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: "max-w-7xl mx-auto", padding: "inline", children: _jsx(Div, { layout: "flex", gap: "2", className: `.5 ${__O.xAuto} [scrollbar-width:none]`, padding: "b-2xs", children: childCategories.map((child) => (_jsxs(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(child.slug)), 
-                            // audit-responsive-wrap-ok: deliberate horizontal-scroll chip row (parent has overflow-x-auto) — each chip staying single-line is the intended design, not hidden content
-                            className: "flex-shrink-0 flex items-center gap-[var(--appkit-space-1-5)] rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-elevated)] px-[var(--appkit-space-4)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium text-[var(--appkit-color-text-muted)] hover:border-primary hover:text-primary transition-colors whitespace-nowrap", children: [child.display?.icon && (_jsx(Span, { className: "leading-none", children: child.display.icon })), child.name, (child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0) > 0 && (_jsx(Span, { size: "xs", color: "muted", children: (child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0).toLocaleString() }))] }, child.id))) }) }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
+    return (_jsxs(Main, { children: [_jsxs(Section, { className: `relative ${__O.hidden} ${hasCover ? "min-h-[220px] md:min-h-[280px]" : "bg-[var(--appkit-color-bg)]"}`, children: [hasCover && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "absolute inset-0", children: _jsx(MediaImage, { src: coverImage, alt: "", size: "banner" }) }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" })] })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsxs(Nav, { layout: "flex", gap: "2xs", textSize: "sm", className: "mb-4", "aria-label": "Breadcrumb", children: [_jsx(Link, { href: String(ROUTES.HOME), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Home" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORIES), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Categories" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Span, { weight: "medium", className: hasCover ? "text-white" : "text-[var(--appkit-color-text)]", children: category?.name ?? slug })] }), _jsx(Heading, { color: "inverse", level: 1, className: `mb-2 ${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: category?.name ?? slug }), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mb-4 ${hasCover ? "/80" : ""}`, size: "base", children: category.description })), _jsxs(Row, { wrap: true, gap: "sm", children: [productCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: "inverse", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "bg-primary/10 text-primary-700 dark:text-primary-400", rounded: "full", padding: "pill-sm-tall", children: [productCount.toLocaleString(), " ", productCount === 1 ? "product" : "products"] })), auctionCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "warning", surface: hasCover ? undefined : "warning-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [auctionCount.toLocaleString(), " ", auctionCount === 1 ? "auction" : "auctions"] })), preOrderCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "info", surface: hasCover ? undefined : "info-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [preOrderCount.toLocaleString(), " ", preOrderCount === 1 ? "pre-order" : "pre-orders"] })), storeCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "success", surface: hasCover ? undefined : "success-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [storeCount.toLocaleString(), " ", storeCount === 1 ? "store" : "stores"] }))] })] })] }), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), childCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: "max-w-7xl mx-auto", padding: "inline", children: Array.from(new Set(childCategories.map((c) => c.tier)))
+                        .sort((a, b) => a - b)
+                        .map((tier) => (_jsxs(Div, { padding: "b-2xs", children: [_jsx(Text, { size: "xs", color: "muted", weight: "medium", className: "mb-[var(--appkit-space-1-5)]", children: tier - (category?.tier ?? 0) === 1
+                                    ? "Subcategories"
+                                    : `${tier - (category?.tier ?? 0)} levels down` }), _jsx(Div, { layout: "flex", gap: "2", className: `.5 ${__O.xAuto} [scrollbar-width:none]`, padding: "b-2xs", children: childCategories.filter((c) => c.tier === tier).map((child) => (_jsxs(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(child.slug)), 
+                                    // audit-responsive-wrap-ok: deliberate horizontal-scroll chip row (parent has overflow-x-auto) — each chip staying single-line is the intended design, not hidden content
+                                    className: "flex-shrink-0 flex items-center gap-[var(--appkit-space-1-5)] rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-elevated)] px-[var(--appkit-space-4)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium text-[var(--appkit-color-text-muted)] hover:border-primary hover:text-primary transition-colors whitespace-nowrap", children: [child.display?.icon && (_jsx(Span, { className: "leading-none", children: child.display.icon })), child.name, (child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0) > 0 && (_jsx(Span, { size: "xs", color: "muted", children: (child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0).toLocaleString() }))] }, child.id))) })] }, tier))) }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
 }

package/dist/features/categories/repository/categories.repository.d.ts

@@ -20,9 +20,73 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * listing/count to include products filed under any of its children.
      */
     getDescendantIds(categoryId: string): Promise<string[]>;
+    /**
+     * Every descendant DOCUMENT at any depth.
+     *
+     * 🛑 PAGINATED, DELIBERATELY. This query used to carry a bare `.limit(100)`,
+     * which silently truncated the subtree — acceptable-ish for a display list,
+     * and corrupting for `reparentSubtree`, which rewrites exactly what this
+     * returns. A move that saw 100 of 130 descendants would leave the other 30
+     * pointing at the old ancestors with no error anywhere. A partial answer to
+     * "what is beneath this node" is worse than a slow one.
+     */
+    getDescendants(categoryId: string): Promise<CategoryDocument[]>;
     getFeaturedCategories(): Promise<CategoryDocument[]>;
     getBrandCategories(limit?: number): Promise<CategoryDocument[]>;
-    updateMetrics(categoryId: string, productDelta: number, auctionDelta: number, productId?: string): Promise<void>;
+    /**
+     * Move `categoryId` under `newParentId`, rewriting the WHOLE subtree.
+     *
+     * 🛑 THE DESCENDANTS ARE THE POINT. The previous `moveCategory` rewrote only
+     * the moved node's own hierarchy fields, so after a move every descendant
+     * still claimed its OLD ancestors — which breaks the `array-contains` subtree
+     * query, the category page's own listing, and `ProductRepository.deriveTaxonomy`
+     * (it reads the leaf's `parentIds` to build each product's `categorySlugs`
+     * chain). That is a data-corruption bug wearing the costume of a stale count.
+     *
+     * 🛑 AND THE METRIC DELTAS LIVE HERE, NOT IN A TRIGGER. `onCategoryWrite` is a
+     * `categories` trigger that writes `categories`, and it is safe only because
+     * every write it makes is gated on `parentIds` CHANGING — a structural guard.
+     * A `metrics.*` write is not covered by that gate, so putting rollup
+     * maintenance there is the Root Cause 92 shape that recursed 1,017,548 times
+     * in 24 hours. Doing it in the same batch as the structural change has no
+     * cycle to guard against in the first place.
+     *
+     * Returns the ids it rewrote, so a caller can log or verify the blast radius.
+     */
+    reparentSubtree(categoryId: string, newParentId: string | null): Promise<string[]>;
+    /**
+     * Re-derive `categorySlugs` for every product inside a moved subtree.
+     *
+     * 🛑 WITHOUT THIS THE MOVE IS ONLY HALF DONE. `categorySlugs` is a
+     * DENORMALISED COPY of the ancestor chain, written by
+     * `ProductRepository.deriveTaxonomy` at product-write time. Moving a category
+     * changes its descendants' chains but writes no product, so every product in
+     * the subtree keeps pointing at the OLD ancestors — it stays listed under the
+     * category it left and never appears under the one it joined. That is the same
+     * unreachable-listing bug the move is supposed to fix, one level down.
+     *
+     * Metric-neutral, and that is load-bearing: `onProductWrite` keys its re-file
+     * branch on the LEAF (`categorySlugs[0]`), which does not change when an
+     * ancestor moves. So these writes early-return in the trigger and apply no
+     * delta — the rollup was already moved by `reparentSubtree`. If this ever
+     * started changing the leaf, it would double-count.
+     *
+     * Reads `products` through `this.db` rather than importing ProductRepository:
+     * no repository in this codebase imports another feature's, because that is
+     * the import chain that drags firebase-admin into a client bundle.
+     */
+    private rewriteProductChains;
+    /**
+     * Commit `writes` in chunks. Firestore caps a batch at 500 operations, and a
+     * subtree rewrite plus its ancestor deltas can exceed that on a deep forest.
+     */
+    private commitChunked;
+    /**
+     * The public move. Everything real lives in `reparentSubtree` so the
+     * delete-cascade path and this share one implementation — two copies of a
+     * subtree rewrite would drift, and only one of them would be the one anybody
+     * tested.
+     */
     moveCategory(input: CategoryMoveInput): Promise<CategoryDocument>;
     buildTree(rootId?: string): Promise<CategoryTreeNode[]>;
     toggleFeatured(categoryId: string, featured: boolean): Promise<CategoryDocument>;

package/dist/features/categories/repository/categories.repository.js

@@ -169,13 +169,42 @@ export class CategoriesRepository extends BaseRepository {
      * listing/count to include products filed under any of its children.
      */
     async getDescendantIds(categoryId) {
+        const docs = await this.getDescendants(categoryId);
+        return docs.map((d) => d.id);
+    }
+    /**
+     * Every descendant DOCUMENT at any depth.
+     *
+     * 🛑 PAGINATED, DELIBERATELY. This query used to carry a bare `.limit(100)`,
+     * which silently truncated the subtree — acceptable-ish for a display list,
+     * and corrupting for `reparentSubtree`, which rewrites exactly what this
+     * returns. A move that saw 100 of 130 descendants would leave the other 30
+     * pointing at the old ancestors with no error anywhere. A partial answer to
+     * "what is beneath this node" is worse than a slow one.
+     */
+    async getDescendants(categoryId) {
         try {
-            const snapshot = await this.db
-                .collection(this.collection)
-                .where("parentIds", "array-contains", categoryId)
-                .limit(100)
-                .get();
-            return snapshot.docs.map((doc) => doc.id);
+            const out = [];
+            const pageSize = 300;
+            let cursor = null;
+            for (;;) {
+                let q = this.db
+                    .collection(this.collection)
+                    .where("parentIds", "array-contains", categoryId)
+                    .orderBy("__name__")
+                    .limit(pageSize);
+                if (cursor)
+                    q = q.startAfter(cursor);
+                const page = await q.get();
+                if (page.empty)
+                    break;
+                for (const doc of page.docs)
+                    out.push(this.mapDoc(doc));
+                if (page.size < pageSize)
+                    break;
+                cursor = page.docs[page.docs.length - 1];
+            }
+            return out;
         }
         catch (error) {
             void normalizeError(error);
@@ -215,89 +244,228 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve brand categories: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    async updateMetrics(categoryId, productDelta, auctionDelta, productId) {
-        try {
-            const category = await this.findByIdOrFail(categoryId);
-            const batch = this.db.batch();
-            const now = new Date();
-            const categoryRef = this.db.collection(this.collection).doc(categoryId);
-            const updates = {
-                "metrics.productCount": increment(productDelta),
-                "metrics.auctionCount": increment(auctionDelta),
-                "metrics.totalProductCount": increment(productDelta),
-                "metrics.totalAuctionCount": increment(auctionDelta),
-                "metrics.totalItemCount": increment(productDelta + auctionDelta),
-                "metrics.lastUpdated": now,
-                updatedAt: now,
-            };
-            if (productId && productDelta !== 0) {
-                updates["metrics.productIds"] =
-                    productDelta > 0 ? arrayUnion(productId) : arrayRemove(productId);
-            }
-            batch.update(categoryRef, updates);
-            for (const ancestorId of category.parentIds) {
-                const ancestorRef = this.db.collection(this.collection).doc(ancestorId);
-                batch.update(ancestorRef, {
-                    "metrics.totalProductCount": increment(productDelta),
-                    "metrics.totalAuctionCount": increment(auctionDelta),
-                    "metrics.totalItemCount": increment(productDelta + auctionDelta),
-                    "metrics.lastUpdated": now,
-                    updatedAt: now,
+    /**
+     * Move `categoryId` under `newParentId`, rewriting the WHOLE subtree.
+     *
+     * 🛑 THE DESCENDANTS ARE THE POINT. The previous `moveCategory` rewrote only
+     * the moved node's own hierarchy fields, so after a move every descendant
+     * still claimed its OLD ancestors — which breaks the `array-contains` subtree
+     * query, the category page's own listing, and `ProductRepository.deriveTaxonomy`
+     * (it reads the leaf's `parentIds` to build each product's `categorySlugs`
+     * chain). That is a data-corruption bug wearing the costume of a stale count.
+     *
+     * 🛑 AND THE METRIC DELTAS LIVE HERE, NOT IN A TRIGGER. `onCategoryWrite` is a
+     * `categories` trigger that writes `categories`, and it is safe only because
+     * every write it makes is gated on `parentIds` CHANGING — a structural guard.
+     * A `metrics.*` write is not covered by that gate, so putting rollup
+     * maintenance there is the Root Cause 92 shape that recursed 1,017,548 times
+     * in 24 hours. Doing it in the same batch as the structural change has no
+     * cycle to guard against in the first place.
+     *
+     * Returns the ids it rewrote, so a caller can log or verify the blast radius.
+     */
+    async reparentSubtree(categoryId, newParentId) {
+        const node = await this.findByIdOrFail(categoryId);
+        const newParent = newParentId
+            ? await this.findByIdOrFail(newParentId)
+            : null;
+        const oldParentId = node.parentIds[node.parentIds.length - 1] ?? null;
+        if (oldParentId === newParentId)
+            return [];
+        const descendants = await this.getDescendants(categoryId);
+        /*
+         * Cycle check. `isValidCategoryMove` only catches self-parenting and
+         * direct-child-as-parent, so a move onto a DEEPER descendant slips past it
+         * and detaches that whole branch from the forest with no error.
+         */
+        if (newParentId && descendants.some((d) => d.id === newParentId)) {
+            throw new DatabaseError(`Invalid category move: ${newParentId} is a descendant of ${categoryId}`);
+        }
+        if (!isValidCategoryMove(categoryId, newParentId, node)) {
+            throw new DatabaseError("Invalid category move: circular reference detected");
+        }
+        const now = new Date();
+        const writes = [];
+        /*
+         * Recompute top-down. A descendant's IMMEDIATE parent never changes when an
+         * ancestor moves, so each node's new fields derive from its parent's new
+         * fields — one pass in tier order, no recursion and no re-reads.
+         */
+        const rebuilt = new Map();
+        const movedFields = calculateCategoryFields(newParent, node.name, categoryId);
+        rebuilt.set(categoryId, { ...node, ...movedFields });
+        writes.push({ id: categoryId, data: { ...movedFields, updatedAt: now } });
+        for (const child of [...descendants].sort((a, b) => a.tier - b.tier)) {
+            const parentId = child.parentIds[child.parentIds.length - 1] ?? "";
+            const parent = rebuilt.get(parentId);
+            // A descendant whose parent is missing from the subtree means the chain is
+            // already broken; leave it alone rather than writing a guess over it.
+            if (!parent)
+                continue;
+            const fields = calculateCategoryFields(parent, child.name, child.id);
+            rebuilt.set(child.id, { ...child, ...fields });
+            writes.push({ id: child.id, data: { ...fields, updatedAt: now } });
+        }
+        /*
+         * Rollup deltas, NETTED PER ANCESTOR.
+         *
+         * The old and new chains usually share ancestors (a move within one root),
+         * and Firestore rejects two updates to the same document in one batch — so a
+         * naive `-total` on the old chain followed by `+total` on the new one either
+         * throws or double-counts. Net them first and drop the zeros; for a move
+         * between siblings that leaves only two documents to touch.
+         *
+         * The delta is the moved node's own ROLLUP, not a subtree rescan: O(depth).
+         * The moved node's own counts do not change — only its ancestors' rollups.
+         */
+        const m = node.metrics ?? {};
+        const dProducts = m?.totalProductCount ?? 0;
+        const dAuctions = m?.totalAuctionCount ?? 0;
+        if (dProducts !== 0 || dAuctions !== 0) {
+            const oldChain = node.parentIds;
+            const newChain = newParent ? [...newParent.parentIds, newParent.id] : [];
+            const net = new Map();
+            for (const id of oldChain)
+                net.set(id, (net.get(id) ?? 0) - 1);
+            for (const id of newChain)
+                net.set(id, (net.get(id) ?? 0) + 1);
+            for (const [id, sign] of net) {
+                if (sign === 0)
+                    continue;
+                writes.push({
+                    id,
+                    data: {
+                        "metrics.totalProductCount": increment(dProducts * sign),
+                        "metrics.totalAuctionCount": increment(dAuctions * sign),
+                        "metrics.totalItemCount": increment((dProducts + dAuctions) * sign),
+                        "metrics.lastUpdated": now,
+                        updatedAt: now,
+                    },
                 });
             }
-            await batch.commit();
+        }
+        if (oldParentId) {
+            writes.push({
+                id: oldParentId,
+                data: { childrenIds: arrayRemove(categoryId), updatedAt: now },
+            });
+        }
+        if (newParentId) {
+            writes.push({
+                id: newParentId,
+                data: {
+                    childrenIds: arrayUnion(categoryId),
+                    isLeaf: false,
+                    updatedAt: now,
+                },
+            });
+        }
+        try {
+            await this.commitChunked(writes);
         }
         catch (error) {
             void normalizeError(error);
-            throw new DatabaseError(`Failed to update category metrics: ${error instanceof Error ? error.message : "Unknown error"}`);
+            throw new DatabaseError(`Failed to move category ${categoryId}: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+        /*
+         * A parent that just lost its last child becomes a leaf again. Done after the
+         * commit because `childrenIds` is an arrayRemove above — reading it before
+         * would see the stale array.
+         */
+        if (oldParentId) {
+            const oldParent = await this.findById(oldParentId);
+            if (oldParent && (oldParent.childrenIds?.length ?? 0) === 0) {
+                await this.db
+                    .collection(this.collection)
+                    .doc(oldParentId)
+                    .update({ isLeaf: true, updatedAt: new Date() });
+            }
         }
+        await this.rewriteProductChains(rebuilt);
+        return writes.map((w) => w.id);
     }
-    async moveCategory(input) {
-        try {
-            const { categoryId, newParentId } = input;
-            const category = await this.findByIdOrFail(categoryId);
-            if (!isValidCategoryMove(categoryId, newParentId, category)) {
-                throw new DatabaseError("Invalid category move: circular reference detected");
-            }
-            let newParent = null;
-            if (newParentId) {
-                newParent = await this.findByIdOrFail(newParentId);
+    /**
+     * Re-derive `categorySlugs` for every product inside a moved subtree.
+     *
+     * 🛑 WITHOUT THIS THE MOVE IS ONLY HALF DONE. `categorySlugs` is a
+     * DENORMALISED COPY of the ancestor chain, written by
+     * `ProductRepository.deriveTaxonomy` at product-write time. Moving a category
+     * changes its descendants' chains but writes no product, so every product in
+     * the subtree keeps pointing at the OLD ancestors — it stays listed under the
+     * category it left and never appears under the one it joined. That is the same
+     * unreachable-listing bug the move is supposed to fix, one level down.
+     *
+     * Metric-neutral, and that is load-bearing: `onProductWrite` keys its re-file
+     * branch on the LEAF (`categorySlugs[0]`), which does not change when an
+     * ancestor moves. So these writes early-return in the trigger and apply no
+     * delta — the rollup was already moved by `reparentSubtree`. If this ever
+     * started changing the leaf, it would double-count.
+     *
+     * Reads `products` through `this.db` rather than importing ProductRepository:
+     * no repository in this codebase imports another feature's, because that is
+     * the import chain that drags firebase-admin into a client bundle.
+     */
+    async rewriteProductChains(rebuilt) {
+        const writes = [];
+        for (const [categoryId, cat] of rebuilt) {
+            // Self first, root last — byte-identical to what deriveTaxonomy produces.
+            const chain = [categoryId, ...(cat.parentIds ?? []).slice().reverse()];
+            /*
+             * Byte-identical to what deriveTaxonomy produces, INCLUDING the falsy
+             * filter — these two must agree, or a product's names chain would differ
+             * depending on whether it was last touched by a product write or a
+             * category move, and nothing would report the difference.
+             */
+            const names = [
+                cat.name,
+                ...(cat.ancestors ?? []).map((a) => a?.name).reverse(),
+            ].filter((n) => !!n);
+            const snap = await this.db
+                .collection("products")
+                .where(PRODUCT_FIELDS.CATEGORY, "==", categoryId)
+                .get();
+            for (const doc of snap.docs) {
+                writes.push({
+                    id: doc.id,
+                    data: { categorySlugs: chain, categoryNames: names, updatedAt: new Date() },
+                });
             }
-            const hierarchyFields = calculateCategoryFields(newParent, category.name, categoryId);
-            const oldParentId = category.parentIds.length > 0
-                ? category.parentIds[category.parentIds.length - 1]
-                : null;
+        }
+        if (!writes.length)
+            return;
+        const products = this.db.collection("products");
+        for (let i = 0; i < writes.length; i += 400) {
             const batch = this.db.batch();
-            const now = new Date();
-            const categoryRef = this.db.collection(this.collection).doc(categoryId);
-            batch.update(categoryRef, {
-                ...hierarchyFields,
-                updatedAt: now,
-            });
-            if (oldParentId) {
-                const oldParentRef = this.db
-                    .collection(this.collection)
-                    .doc(oldParentId);
-                batch.update(oldParentRef, {
-                    childrenIds: arrayRemove(categoryId),
-                    updatedAt: now,
-                });
-                const oldParent = await this.findById(oldParentId);
-                if (oldParent && oldParent.childrenIds.length === 1) {
-                    batch.update(oldParentRef, { isLeaf: true });
-                }
+            for (const w of writes.slice(i, i + 400)) {
+                batch.update(products.doc(w.id), w.data);
             }
-            if (newParentId) {
-                const newParentRef = this.db
-                    .collection(this.collection)
-                    .doc(newParentId);
-                batch.update(newParentRef, {
-                    childrenIds: arrayUnion(categoryId),
-                    isLeaf: false,
-                    updatedAt: now,
-                });
+            await batch.commit();
+        }
+    }
+    /**
+     * Commit `writes` in chunks. Firestore caps a batch at 500 operations, and a
+     * subtree rewrite plus its ancestor deltas can exceed that on a deep forest.
+     */
+    async commitChunked(writes, chunkSize = 400) {
+        const colRef = this.db.collection(this.collection);
+        for (let i = 0; i < writes.length; i += chunkSize) {
+            const batch = this.db.batch();
+            for (const w of writes.slice(i, i + chunkSize)) {
+                batch.update(colRef.doc(w.id), w.data);
             }
             await batch.commit();
+        }
+    }
+    /**
+     * The public move. Everything real lives in `reparentSubtree` so the
+     * delete-cascade path and this share one implementation — two copies of a
+     * subtree rewrite would drift, and only one of them would be the one anybody
+     * tested.
+     */
+    async moveCategory(input) {
+        try {
+            const { categoryId, newParentId } = input;
+            await this.reparentSubtree(categoryId, newParentId ?? null);
             return this.findByIdOrFail(categoryId);
         }
         catch (error) {

package/dist/features/categories/types/index.d.ts

@@ -21,11 +21,11 @@ export interface CategoryMetrics {
     totalItemCount: number;
     lastUpdated?: string;
 }
-export interface CategoryAncestor {
+export type CategoryAncestor = {
     id: string;
     name: string;
     tier: number;
-}
+};
 export interface CategoryItem {
     id: string;
     categoryType?: CategoryType;

package/dist/features/tester/seed-data/authored/admin__admin-detail-round-trips.d.ts

@@ -0,0 +1,2 @@
+import type { AuthoredCase } from "./_types";
+export declare const authored: Record<string, AuthoredCase>;