@mohasinac/appkit 4.45.0 → 4.46.0

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

@@ -1,3 +1,4 @@
+import { type CategoryCountsDocument } from "../schemas/category-counts";
 import { BaseRepository, type FirebaseSieveFields, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
 import { type CategoryCreateInput, type CategoryDocument, type CategoryMoveInput, type CategoryTreeNode } from "../schemas";
 import type { FirestoreDocument, JsonValue } from "@mohasinac/appkit";
@@ -157,6 +158,36 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * The caller must have already fetched `parentIds` for the category.
      */
     updateMetricsInBatch(batch: import("firebase-admin/firestore").WriteBatch, categoryId: string, parentIds: string[], productDelta: number, auctionDelta: number, productId?: string): void;
+    /**
+     * I3 — the same live metric update, for a product filed under SEVERAL
+     * categories at once.
+     *
+     * 🛑 WHY THIS EXISTS RATHER THAN CALLING THE SINGLE VERSION IN A LOOP.
+     * **Firestore rejects a batch containing two writes to the same document.**
+     * Two assignments whose chains share an ancestor would each stage a
+     * `batch.update` on that ancestor, and the whole batch throws — losing every
+     * increment in it, not just the duplicate.
+     *
+     * Under the one-per-root rule the chains are disjoint and it cannot happen.
+     * That is not sufficient grounds to skip the aggregation: the rule is
+     * enforced at ONE write path (`deriveTaxonomy`), while this trigger fires for
+     * whatever reached Firestore — including a seeded row and the admin
+     * `.passthrough()` route, neither of which passes through it. Aggregating
+     * costs a Map; being wrong costs a silently dropped counter.
+     *
+     * So: one `batch.update` per DISTINCT document, with the own-deltas and the
+     * rollup-deltas summed per id first.
+     *
+     * 🛑 `own` lands on every assignment and `total` lands once per distinct id
+     * across all their chains — which is the arithmetic `CategoryCountsDocument`
+     * states: `total` already includes `own`, and the two are never summed.
+     */
+    updateMetricsForAssignmentsInBatch(batch: import("firebase-admin/firestore").WriteBatch, assignments: Array<{
+        id: string;
+        parentIds: string[];
+    }>, productDelta: number, auctionDelta: number, productId?: string, 
+    /** A brand row: flat, so own and rollup move together. */
+    brandId?: string | null): void;
     /**
      * Cloud Functions: full-overwrite category metrics (nightly reconciliation).
      *
@@ -182,6 +213,19 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * a true 65. Nothing errored, and no page looked broken; a wrong number is
      * simply a number.
      */
+    /**
+     * G3b — this category's OWN and ROLLUP counts, as one document read.
+     *
+     * 🛑 Returns `null` when no counts document exists, NEVER a zeroed object.
+     * An unknown count must stay distinguishable from a count of nothing (Root
+     * Cause #72), so the caller falls back to `metrics` and renders exactly as
+     * it did before — which is what makes `categoryCounts` additive rather than
+     * a regression on every category until its first product mutation.
+     *
+     * One doc by id: no index, no query, and safe inside a page already at Rule
+     * #6's round-trip budget provided the caller runs it in parallel.
+     */
+    getLiveCounts(categoryId: string): Promise<CategoryCountsDocument | null>;
     setMetrics(categoryId: string, m: {
         /** Items filed DIRECTLY under this category. */
         productCount: number;
@@ -206,6 +250,27 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * Used by /api/sublisting-categories/[slug]/listings.
      */
     getSublistingListings(sublistingId: string, limit?: number): Promise<FirestoreDocument[]>;
+    /**
+     * I4 — re-cache a renamed node's name into every descendant's `ancestors[]`,
+     * and rebuild their `searchTxt`.
+     *
+     * 🛑 WHY A RENAME NEEDS THIS AT ALL. `ancestors[]` is `{id, name, tier}` —
+     * a denormalised copy of a name that lives on another document. Nothing
+     * re-synced it, so renaming "Beyblade Burst" left every node beneath it
+     * holding the old string, and `buildCategorySearchTxt` indexes those names
+     * deliberately: typing "burst" reaches `category-lost-longinus` BECAUSE
+     * Beyblade Burst is one of its ancestors. So a rename silently broke lineage
+     * search for the whole subtree while the node's own page looked perfect.
+     *
+     * Mirror-drift (Root Cause #42) on the taxonomy's own axis, and the same
+     * class as `storeName` on a product — which already has a backfill job for
+     * exactly this reason.
+     *
+     * Returns the ids actually written. A node already carrying the right names
+     * is skipped, so a re-run costs nothing — which is what lets an
+     * at-least-once trigger start the job that calls this.
+     */
+    refreshSubtreeAncestors(categoryId: string): Promise<string[]>;
     /**
      * SB-UNI-B — delete a sublisting category and unlink all products
      * that referenced it. Mirrors the cascade behavior of the old

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

@@ -1,4 +1,5 @@
 import { normalizeError } from "../../../errors/normalize.js";
+import { CATEGORY_COUNTS_COLLECTION, } from "../schemas/category-counts.js";
 import { increment, arrayUnion, arrayRemove, } from "../../../contracts/field-ops.js";
 import { DatabaseError } from "../../../errors/index.js";
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, applySieveToFirestore, } from "../../../providers/db-firebase/index.js";
@@ -701,35 +702,81 @@ export class CategoriesRepository extends BaseRepository {
      * The caller must have already fetched `parentIds` for the category.
      */
     updateMetricsInBatch(batch, categoryId, parentIds, productDelta, auctionDelta, productId) {
+        this.updateMetricsForAssignmentsInBatch(batch, [{ id: categoryId, parentIds }], productDelta, auctionDelta, productId);
+    }
+    /**
+     * I3 — the same live metric update, for a product filed under SEVERAL
+     * categories at once.
+     *
+     * 🛑 WHY THIS EXISTS RATHER THAN CALLING THE SINGLE VERSION IN A LOOP.
+     * **Firestore rejects a batch containing two writes to the same document.**
+     * Two assignments whose chains share an ancestor would each stage a
+     * `batch.update` on that ancestor, and the whole batch throws — losing every
+     * increment in it, not just the duplicate.
+     *
+     * Under the one-per-root rule the chains are disjoint and it cannot happen.
+     * That is not sufficient grounds to skip the aggregation: the rule is
+     * enforced at ONE write path (`deriveTaxonomy`), while this trigger fires for
+     * whatever reached Firestore — including a seeded row and the admin
+     * `.passthrough()` route, neither of which passes through it. Aggregating
+     * costs a Map; being wrong costs a silently dropped counter.
+     *
+     * So: one `batch.update` per DISTINCT document, with the own-deltas and the
+     * rollup-deltas summed per id first.
+     *
+     * 🛑 `own` lands on every assignment and `total` lands once per distinct id
+     * across all their chains — which is the arithmetic `CategoryCountsDocument`
+     * states: `total` already includes `own`, and the two are never summed.
+     */
+    updateMetricsForAssignmentsInBatch(batch, assignments, productDelta, auctionDelta, productId, 
+    /** A brand row: flat, so own and rollup move together. */
+    brandId) {
         const now = new Date();
         const colRef = this.db.collection(this.collection);
-        const directRef = colRef.doc(categoryId);
-        const directUpdate = {
-            "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) {
-            directUpdate["metrics.productIds"] =
-                productDelta > 0 ? arrayUnion(productId) : arrayRemove(productId);
-        }
-        if (productId && auctionDelta !== 0) {
-            directUpdate["metrics.auctionIds"] =
-                auctionDelta > 0 ? arrayUnion(productId) : arrayRemove(productId);
-        }
-        batch.update(directRef, directUpdate);
-        for (const ancestorId of parentIds) {
-            batch.update(colRef.doc(ancestorId), {
+        /** id → how many times `own` moves, and whether the rollup moves. */
+        const own = new Map();
+        const rollup = new Set();
+        for (const a of assignments) {
+            if (!a.id)
+                continue;
+            own.set(a.id, (own.get(a.id) ?? 0) + 1);
+            rollup.add(a.id);
+            for (const ancestorId of a.parentIds)
+                if (ancestorId)
+                    rollup.add(ancestorId);
+        }
+        if (brandId) {
+            own.set(brandId, (own.get(brandId) ?? 0) + 1);
+            rollup.add(brandId);
+        }
+        for (const id of rollup) {
+            /*
+             * `ownTimes` is 0 for a pure ancestor and 1 for an assignment. It is only
+             * ever >1 if the SAME id was assigned twice, which `readAssignments`
+             * dedupes — kept as a multiplier rather than a boolean so that case
+             * stays arithmetically honest instead of silently collapsing.
+             */
+            const ownTimes = own.get(id) ?? 0;
+            const update = {
                 "metrics.totalProductCount": increment(productDelta),
                 "metrics.totalAuctionCount": increment(auctionDelta),
                 "metrics.totalItemCount": increment(productDelta + auctionDelta),
                 "metrics.lastUpdated": now,
                 updatedAt: now,
-            });
+            };
+            if (ownTimes > 0) {
+                update["metrics.productCount"] = increment(productDelta * ownTimes);
+                update["metrics.auctionCount"] = increment(auctionDelta * ownTimes);
+                if (productId && productDelta !== 0) {
+                    update["metrics.productIds"] =
+                        productDelta > 0 ? arrayUnion(productId) : arrayRemove(productId);
+                }
+                if (productId && auctionDelta !== 0) {
+                    update["metrics.auctionIds"] =
+                        auctionDelta > 0 ? arrayUnion(productId) : arrayRemove(productId);
+                }
+            }
+            batch.update(colRef.doc(id), update);
         }
     }
     /**
@@ -757,6 +804,25 @@ export class CategoriesRepository extends BaseRepository {
      * a true 65. Nothing errored, and no page looked broken; a wrong number is
      * simply a number.
      */
+    /**
+     * G3b — this category's OWN and ROLLUP counts, as one document read.
+     *
+     * 🛑 Returns `null` when no counts document exists, NEVER a zeroed object.
+     * An unknown count must stay distinguishable from a count of nothing (Root
+     * Cause #72), so the caller falls back to `metrics` and renders exactly as
+     * it did before — which is what makes `categoryCounts` additive rather than
+     * a regression on every category until its first product mutation.
+     *
+     * One doc by id: no index, no query, and safe inside a page already at Rule
+     * #6's round-trip budget provided the caller runs it in parallel.
+     */
+    async getLiveCounts(categoryId) {
+        const snap = await this.db
+            .collection(CATEGORY_COUNTS_COLLECTION)
+            .doc(categoryId)
+            .get();
+        return snap.exists ? snap.data() : null;
+    }
     async setMetrics(categoryId, m) {
         await this.db
             .collection(this.collection)
@@ -813,6 +879,86 @@ export class CategoriesRepository extends BaseRepository {
             .get();
         return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
     }
+    /**
+     * I4 — re-cache a renamed node's name into every descendant's `ancestors[]`,
+     * and rebuild their `searchTxt`.
+     *
+     * 🛑 WHY A RENAME NEEDS THIS AT ALL. `ancestors[]` is `{id, name, tier}` —
+     * a denormalised copy of a name that lives on another document. Nothing
+     * re-synced it, so renaming "Beyblade Burst" left every node beneath it
+     * holding the old string, and `buildCategorySearchTxt` indexes those names
+     * deliberately: typing "burst" reaches `category-lost-longinus` BECAUSE
+     * Beyblade Burst is one of its ancestors. So a rename silently broke lineage
+     * search for the whole subtree while the node's own page looked perfect.
+     *
+     * Mirror-drift (Root Cause #42) on the taxonomy's own axis, and the same
+     * class as `storeName` on a product — which already has a backfill job for
+     * exactly this reason.
+     *
+     * Returns the ids actually written. A node already carrying the right names
+     * is skipped, so a re-run costs nothing — which is what lets an
+     * at-least-once trigger start the job that calls this.
+     */
+    async refreshSubtreeAncestors(categoryId) {
+        const descendants = await this.getDescendants(categoryId);
+        if (descendants.length === 0)
+            return [];
+        /*
+         * Every id named by any descendant's chain, resolved once. `parentIds`
+         * holds the FULL chain, so this is a single pass rather than a walk — and
+         * the ids are deduped across the subtree, so a 200-node subtree sharing
+         * four ancestors costs four reads, not 800.
+         */
+        const needed = new Set();
+        for (const d of descendants)
+            for (const id of d.parentIds ?? [])
+                needed.add(id);
+        const byId = new Map();
+        const ids = [...needed];
+        for (let i = 0; i < ids.length; i += 30) {
+            const refs = ids.slice(i, i + 30).map((id) => this.db.collection(this.collection).doc(id));
+            const snaps = await this.db.getAll(...refs);
+            for (const snap of snaps) {
+                if (snap.exists)
+                    byId.set(snap.id, { id: snap.id, ...snap.data() });
+            }
+        }
+        const writes = [];
+        for (const d of descendants) {
+            /*
+             * `ancestors` is root-first, matching `parentIds`. Rebuilt from the live
+             * documents rather than patched in place, so a tier that also changed is
+             * picked up in the same pass.
+             */
+            const ancestors = (d.parentIds ?? [])
+                .map((id) => byId.get(id))
+                .filter((c) => !!c)
+                .map((c) => ({ id: c.id, name: c.name, tier: c.tier }));
+            const same = (d.ancestors ?? []).length === ancestors.length &&
+                (d.ancestors ?? []).every((a, i) => a?.id === ancestors[i]?.id && a?.name === ancestors[i]?.name);
+            if (same)
+                continue;
+            /*
+             * `searchTxt` is rebuilt with the NEW ancestors, not the stored ones —
+             * `buildSearchTxtFor` reads the document it is handed, so passing the
+             * stale row would re-index the stale names and the rename would appear
+             * to have worked while changing nothing searchable.
+             */
+            const searchTxt = buildCategorySearchTxt({ ...d, ancestors });
+            writes.push({
+                id: d.id,
+                data: {
+                    ancestors,
+                    ...(searchTxt ? { searchTxt } : {}),
+                    updatedAt: new Date(),
+                },
+            });
+        }
+        if (writes.length === 0)
+            return [];
+        await this.commitChunked(writes);
+        return writes.map((w) => w.id);
+    }
     /**
      * SB-UNI-B — delete a sublisting category and unlink all products
      * that referenced it. Mirrors the cascade behavior of the old

package/dist/features/categories/repository/category-counts.d.ts

@@ -0,0 +1,143 @@
+/**
+ * G3b — the incremental leaf→root counter.
+ *
+ * 🛑 MAINTAINED FROM THE REPOSITORY, NOT A FIRESTORE TRIGGER, and this is the
+ * decisive constraint rather than a preference. `FieldValue.increment` is
+ * atomic but **not idempotent**, and a Firestore trigger is delivered
+ * at-least-once — so a redelivered trigger double-counts permanently and
+ * invisibly, which is the worst failure available here (a wrong number is just
+ * a number; nothing errors). From `ProductRepository` a retry is the caller's
+ * and the increments are one batch.
+ *
+ * It walks the STORED chain, which is what makes it duplicate-free and acyclic
+ * by construction rather than by care:
+ *
+ *   - `product.categorySlugs` is already `[leaf, …ancestors, root]`, derived by
+ *     `deriveTaxonomy` on create and update. Each ancestor appears exactly
+ *     once, so incrementing every element once cannot double-count.
+ *   - It comes from `buildCategoryTree`'s DFS over a forest, so it is acyclic
+ *     by construction and bounded at 5 (tiers 0–4).
+ *
+ * 🛑 Do NOT walk parent-by-parent at write time. That is N reads per mutation
+ * and it reintroduces the cycle question the stored chain already answers.
+ */
+import type { ListingType } from "../../products/types";
+/** The only product fields this module reads. */
+export interface CountableProductRow {
+    /** I3 — the ASSIGNED categories. Absent on every product written before I1. */
+    categoryIds?: string[] | null;
+    categorySlugs?: string[] | null;
+    category?: string | null;
+    brandSlug?: string | null;
+    listingType?: ListingType | string | null;
+    isLot?: boolean;
+}
+/**
+ * One product's contribution to the counters, or `null` when it contributes
+ * nothing.
+ *
+ * `countsNow` is the caller's availability verdict — this module deliberately
+ * does NOT compute it, so there is exactly one implementation of "is this row
+ * available" in the codebase (`isListingRowAvailable`) and no chance of a
+ * second, disagreeing copy. Root Cause #73 is what four partial copies of that
+ * predicate cost.
+ */
+export interface CountDelta {
+    /**
+     * The ASSIGNED categories — where `own` moves. One entry per assignment.
+     *
+     * 🛑 I3: this was a single `leaf`. A product can now be filed under several
+     * categories (at most one per root), and it is genuinely "here" in each of
+     * them — so `own` bumps at every one, not just the default.
+     *
+     * `owns[0]` is the DEFAULT assignment, because the closure is ordered
+     * default-chain-first and this is read from its head.
+     */
+    owns: string[];
+    /**
+     * The whole chain — where `total` moves. INCLUDES the leaf.
+     *
+     * 🛑 `total` therefore includes `own` and the two must never be summed; see
+     * the invariant on `CategoryCountsDocument`. The leaf ends up with own=1 and
+     * total=1 for one listing, which is one count in each of two fields
+     * answering two different questions — not the same item counted twice.
+     */
+    chain: string[];
+    /**
+     * The brand row, counted as a FLAT dimension: own AND total both move,
+     * because a brand has no category children of its own beyond what points at
+     * it — so `own === total` by construction and `descendantTotalFor` is 0.
+     *
+     * 🛑 This existed in `countersReconcile` and NOT here until the own/children
+     * review. Without it the incremental path never touched a brand, so every
+     * brand's counter stayed stale until the nightly pass and then "drifted" in
+     * the log every single night — an audit signal permanently stuck on,
+     * which is the same as no signal at all.
+     */
+    brand: string | null;
+    listingType: ListingType;
+    isLot: boolean;
+}
+/**
+ * Read a product's countable identity.
+ *
+ * Mirrors `countersReconcile.tallyProduct`'s own field selection exactly —
+ * `categorySlugs[0]` first, then the `@deprecated` scalar `category` — so the
+ * incremental and the nightly values can agree. Two different leaf selections
+ * would drift silently and the reconciler would "correct" a count that was
+ * right.
+ */
+export declare function describeCountable(row: CountableProductRow): CountDelta | null;
+/**
+ * Whether a mutation can possibly have changed the counters.
+ *
+ * 🛑 THE BUG THIS EXISTS TO PREVENT, and the plan called it in advance: a guard
+ * that asks only "did the taxonomy change?" MISSES EVERY STATUS TRANSITION.
+ * `draft → published` changes no `categorySlugs` at all, so the count would
+ * never move — silently, on a page that looks correct. Same for
+ * `published → archived`, a sell-out, and a soft delete.
+ *
+ * So the comparison is over (chain, leaf, listingType, isLot, countsNow), and
+ * the availability verdict is a first-class input rather than an afterthought.
+ */
+export declare function countsChanged(before: {
+    delta: CountDelta | null;
+    countsNow: boolean;
+}, after: {
+    delta: CountDelta | null;
+    countsNow: boolean;
+}): boolean;
+/** A single field path → increment, keyed so the batch can merge them. */
+export type CountPatch = Map<string, Map<string, number>>;
+/**
+ * Build the field-path increments for one product transition.
+ *
+ * `sign` is +1 for an addition and −1 for a removal; an update is expressed as
+ * a removal of the old shape followed by an addition of the new, which is why
+ * a move between leaves nets to −1 on the old chain and +1 on the new with no
+ * node double-counted.
+ */
+export declare function buildCountPatch(deltas: Array<{
+    delta: CountDelta | null;
+    sign: 1 | -1;
+}>): CountPatch;
+/**
+ * Apply a patch.
+ *
+ * `set(..., { merge: true })` rather than `update`, because the counts document
+ * may not exist yet: `update` on a missing document throws, and a counter that
+ * refuses to start is worse than one that starts at the first mutation. Merge
+ * also leaves the OTHER listing types' keys untouched, which is what keeps the
+ * map `Partial`.
+ *
+ * 🛑 Failure is swallowed deliberately, and this is the one place in this
+ * codebase where that is right: a count is a display number, and failing a
+ * seller's publish because an ancestor counter could not be bumped would trade
+ * a cosmetic staleness for a lost listing. The nightly reconciler is the
+ * backstop — its `drifted` count is how a missed increment becomes visible.
+ */
+export declare function applyCountPatch(db: {
+    collection(name: string): any;
+}, patch: CountPatch, onError?: (err: {
+    message: string;
+}) => void): Promise<void>;

package/dist/features/categories/repository/category-counts.js

@@ -0,0 +1,224 @@
+/**
+ * G3b — the incremental leaf→root counter.
+ *
+ * 🛑 MAINTAINED FROM THE REPOSITORY, NOT A FIRESTORE TRIGGER, and this is the
+ * decisive constraint rather than a preference. `FieldValue.increment` is
+ * atomic but **not idempotent**, and a Firestore trigger is delivered
+ * at-least-once — so a redelivered trigger double-counts permanently and
+ * invisibly, which is the worst failure available here (a wrong number is just
+ * a number; nothing errors). From `ProductRepository` a retry is the caller's
+ * and the increments are one batch.
+ *
+ * It walks the STORED chain, which is what makes it duplicate-free and acyclic
+ * by construction rather than by care:
+ *
+ *   - `product.categorySlugs` is already `[leaf, …ancestors, root]`, derived by
+ *     `deriveTaxonomy` on create and update. Each ancestor appears exactly
+ *     once, so incrementing every element once cannot double-count.
+ *   - It comes from `buildCategoryTree`'s DFS over a forest, so it is acyclic
+ *     by construction and bounded at 5 (tiers 0–4).
+ *
+ * 🛑 Do NOT walk parent-by-parent at write time. That is N reads per mutation
+ * and it reintroduces the cycle question the stored chain already answers.
+ */
+import { increment, serverTimestamp } from "../../../contracts/field-ops.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { CATEGORY_COUNTS_COLLECTION } from "../schemas/category-counts.js";
+const DEFAULT_LISTING_TYPE = "standard";
+/**
+ * Read a product's countable identity.
+ *
+ * Mirrors `countersReconcile.tallyProduct`'s own field selection exactly —
+ * `categorySlugs[0]` first, then the `@deprecated` scalar `category` — so the
+ * incremental and the nightly values can agree. Two different leaf selections
+ * would drift silently and the reconciler would "correct" a count that was
+ * right.
+ */
+export function describeCountable(row) {
+    const chainRaw = Array.isArray(row.categorySlugs) ? row.categorySlugs : [];
+    /*
+     * I3 — the ASSIGNED list is what `own` keys on, and it is read from
+     * `categoryIds` with the old single-leaf selection as the fallback.
+     *
+     * 🛑 The fallback is not legacy tidiness, it is required: `categoryIds` was
+     * added in I1, so every product written before it has only `categorySlugs`,
+     * and the nightly reconciler reads the same two fields in the same order. Two
+     * different selections would drift silently and the reconciler would
+     * "correct" a count that was right.
+     */
+    const ownsRaw = Array.isArray(row.categoryIds) && row.categoryIds.length > 0
+        ? row.categoryIds
+        : [chainRaw[0] || row.category || ""];
+    const ownSeen = new Set();
+    const owns = [];
+    for (const id of ownsRaw) {
+        if (!id || ownSeen.has(id))
+            continue;
+        ownSeen.add(id);
+        owns.push(id);
+    }
+    if (owns.length === 0)
+        return null;
+    /*
+     * Dedupe the chain. The one real duplicate risk the stored closure does NOT
+     * remove is a product filed under two leaves that share an ancestor — the
+     * shared ancestor would otherwise be incremented twice for one listing.
+     *
+     * 🛑 Under the one-per-root rule that cannot happen, and the dedupe stays
+     * anyway: the rule is enforced at ONE write path, while this runs on every
+     * row that reaches Firestore — including a seeded row and an admin
+     * `.passthrough()` write, neither of which passes through it. A belt, and the
+     * cheaper of the two places to be wrong.
+     */
+    const seen = new Set();
+    const chain = [];
+    for (const id of [...owns, ...chainRaw]) {
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        chain.push(id);
+    }
+    /*
+     * 🛑 Never count the brand twice. If a row's leaf id were also its brand id,
+     * the brand bump below would land on a category already bumped by the chain.
+     * It cannot happen with today's `category-` / `brand-` prefixes, which is
+     * exactly why it is worth guarding rather than trusting: the prefixes are a
+     * convention and this is an arithmetic invariant.
+     */
+    const brandSlug = row.brandSlug || null;
+    const brand = brandSlug && !seen.has(brandSlug) ? brandSlug : null;
+    return {
+        owns,
+        chain,
+        brand,
+        listingType: row.listingType || DEFAULT_LISTING_TYPE,
+        isLot: row.isLot === true,
+    };
+}
+/**
+ * Whether a mutation can possibly have changed the counters.
+ *
+ * 🛑 THE BUG THIS EXISTS TO PREVENT, and the plan called it in advance: a guard
+ * that asks only "did the taxonomy change?" MISSES EVERY STATUS TRANSITION.
+ * `draft → published` changes no `categorySlugs` at all, so the count would
+ * never move — silently, on a page that looks correct. Same for
+ * `published → archived`, a sell-out, and a soft delete.
+ *
+ * So the comparison is over (chain, leaf, listingType, isLot, countsNow), and
+ * the availability verdict is a first-class input rather than an afterthought.
+ */
+export function countsChanged(before, after) {
+    const b = before.countsNow ? before.delta : null;
+    const a = after.countsNow ? after.delta : null;
+    if (!b && !a)
+        return false;
+    if (!b || !a)
+        return true;
+    return (b.owns.length !== a.owns.length ||
+        b.owns.some((id, i) => id !== a.owns[i]) ||
+        b.brand !== a.brand ||
+        b.listingType !== a.listingType ||
+        b.isLot !== a.isLot ||
+        b.chain.length !== a.chain.length ||
+        b.chain.some((id, i) => id !== a.chain[i]));
+}
+function bump(patch, categoryId, field, by) {
+    let doc = patch.get(categoryId);
+    if (!doc) {
+        doc = new Map();
+        patch.set(categoryId, doc);
+    }
+    doc.set(field, (doc.get(field) ?? 0) + by);
+}
+/**
+ * Build the field-path increments for one product transition.
+ *
+ * `sign` is +1 for an addition and −1 for a removal; an update is expressed as
+ * a removal of the old shape followed by an addition of the new, which is why
+ * a move between leaves nets to −1 on the old chain and +1 on the new with no
+ * node double-counted.
+ */
+export function buildCountPatch(deltas) {
+    const patch = new Map();
+    for (const { delta, sign } of deltas) {
+        if (!delta)
+            continue;
+        const ownField = delta.isLot ? "lots.own" : `own.${delta.listingType}`;
+        const totalField = delta.isLot ? "lots.total" : `total.${delta.listingType}`;
+        /*
+         * Every ASSIGNMENT gets `own`; the whole deduped closure gets `total`.
+         *
+         * 🛑 `own` at each one is the point of I3: a product assigned to both
+         * category-dragoon-g and category-beyblade is genuinely filed in both, and
+         * each page's "N here" must say so. `total` is still one bump per closure
+         * entry, so a shared ancestor moves by 1 for the listing rather than by the
+         * number of assignments that reach it.
+         */
+        for (const id of delta.owns)
+            bump(patch, id, ownField, sign);
+        for (const id of delta.chain)
+            bump(patch, id, totalField, sign);
+        // A brand is flat: own and total move together, so its descendant count
+        // derives to 0 rather than to a negative number.
+        if (delta.brand) {
+            bump(patch, delta.brand, ownField, sign);
+            bump(patch, delta.brand, totalField, sign);
+        }
+    }
+    /*
+     * Drop net-zero fields. A move WITHIN one leaf (a title edit on a row whose
+     * chain did not change) cancels to nothing, and writing `increment(0)` would
+     * still be a write — one per ancestor, on the hottest path in the app.
+     */
+    for (const [catId, fields] of patch) {
+        for (const [field, by] of fields)
+            if (by === 0)
+                fields.delete(field);
+        if (fields.size === 0)
+            patch.delete(catId);
+    }
+    return patch;
+}
+/**
+ * Apply a patch.
+ *
+ * `set(..., { merge: true })` rather than `update`, because the counts document
+ * may not exist yet: `update` on a missing document throws, and a counter that
+ * refuses to start is worse than one that starts at the first mutation. Merge
+ * also leaves the OTHER listing types' keys untouched, which is what keeps the
+ * map `Partial`.
+ *
+ * 🛑 Failure is swallowed deliberately, and this is the one place in this
+ * codebase where that is right: a count is a display number, and failing a
+ * seller's publish because an ancestor counter could not be bumped would trade
+ * a cosmetic staleness for a lost listing. The nightly reconciler is the
+ * backstop — its `drifted` count is how a missed increment becomes visible.
+ */
+export async function applyCountPatch(db, patch, onError) {
+    if (patch.size === 0)
+        return;
+    try {
+        const col = db.collection(CATEGORY_COUNTS_COLLECTION);
+        await Promise.all(Array.from(patch, ([categoryId, fields]) => {
+            /*
+             * `FieldSentinel` rather than `unknown`: every value here is either
+             * the id string or a Firestore sentinel (`increment` / `serverTimestamp`),
+             * and `Record<string, unknown>` would be a dodge that `audit-unknown-leakage`
+             * correctly refuses — it says nothing about what may be written.
+             */
+            const payload = {
+                id: categoryId,
+                updatedAt: serverTimestamp(),
+            };
+            for (const [field, by] of fields)
+                payload[field] = increment(by);
+            return col.doc(categoryId).set(payload, { merge: true });
+        }));
+    }
+    catch (err) {
+        // Typed before anything downstream touches it (Root Cause #31) — the
+        // caller logs `.message`, and an `unknown` escaping a catch is how a
+        // non-Error throw becomes "[object Object]" in a log line.
+        onError?.(normalizeError(err));
+    }
+}