@mohasinac/appkit 4.45.0 → 4.47.0

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

@@ -115,7 +115,15 @@ export function CategoryTemplatePicker({ categoryId, condition, context, isDescr
      * accurate BEFORE the seller commits. A note that appears only after the
      * text lands is a report on something they can no longer choose about.
      */
-    const filled = React.useMemo(() => (template ? interpolate(template.body, context) : null), [template, context]);
+    /*
+     * 🛑 Server slots merge UNDERNEATH the form's context, so a draft-derived
+     * value always wins. The two key spaces are disjoint today — the form knows
+     * the listing, the server knows the category — and this ordering is what
+     * keeps it safe if they ever overlap: the more specific source is the one
+     * holding the item in front of the seller.
+     */
+    const resolved = React.useMemo(() => ({ ...(data?.slots ?? {}), ...context }), [data?.slots, context]);
+    const filled = React.useMemo(() => (template ? interpolate(template.body, resolved) : null), [template, resolved]);
     /*
      * Auto-fill when the seller owns nothing. Deliberately an effect rather than
      * a render-time write: the body has to reach the draft, which is the

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>;