@mohasinac/appkit 4.44.0 → 4.46.0

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));
+    }
+}

package/dist/features/categories/repository/price-index.repository.d.ts

@@ -60,6 +60,21 @@ export interface PriceIndexBand {
     min: number;
     median: number;
     max: number;
+    /**
+     * The arithmetic MEAN, carried alongside the median rather than instead of
+     * it.
+     *
+     * 🛑 They are different quantities and the gap between them is information,
+     * so neither substitutes for the other — the same discipline the market-vs-
+     * sold pair is held to. On a collectibles leaf the two routinely diverge:
+     * nine ₹900 sales and one ₹9,000 grail give a median of ₹900 and a mean of
+     * ₹1,710, and a buyer told only the mean concludes the item costs ₹1,710,
+     * while a seller told only the median prices a mint example like a loose one.
+     *
+     * Which is "the average" depends on the question, which is exactly why the
+     * renderer shows both and labels them rather than picking.
+     */
+    mean: number;
     /**
      * 🛑 The confidence signal, and the UI must render a small one as a sample
      * size with NO headline number — the same discipline as `truncated`
@@ -68,12 +83,49 @@ export interface PriceIndexBand {
      */
     sampleSize: number;
     byPath?: PriceIndexByPath;
+    /**
+     * Per-CONDITION bands within this listing type.
+     *
+     * 🛑 The single most requested breakdown and the one the blended band hides.
+     * Condition is the dominant price variable in collectibles — the crawl
+     * measured WHS keeping midfake/damaged/incomplete stock in a separate
+     * Clearance category precisely because it cannot be priced with the rest, and
+     * hobson's "Without Box" group runs at a ₹599 median against ₹4,499 for the
+     * same boxed figures. A leaf band spanning `new` and `poor` is an average of
+     * two different markets.
+     *
+     * Keyed by `ProductDocument.condition`. Absent when no sale in the window
+     * recorded one — NOT zeroed, and not back-filled with a guess: "we do not
+     * know what condition these sold in" is a different statement from "they sold
+     * in unknown condition", and only the first is true.
+     */
+    byCondition?: Record<string, PriceIndexConditionBand>;
     lastSold?: {
         amount: number;
         at: Date;
         via?: "standard" | "auction" | "offer";
     };
 }
+/**
+ * A condition slice. Deliberately NARROWER than `PriceIndexBand` — no
+ * `byPath`, no nested `byCondition`, no recursion.
+ *
+ * Slicing a 90-day leaf window by both listing type and condition leaves
+ * single-digit samples fast, so a third axis inside it would be arithmetic on
+ * one sale. `sampleSize` is here for exactly that reason and the renderer must
+ * gate on it with the same threshold as the parent.
+ */
+export interface PriceIndexConditionBand {
+    min: number;
+    median: number;
+    max: number;
+    mean: number;
+    sampleSize: number;
+    lastSold?: {
+        amount: number;
+        at: Date;
+    };
+}
 /** One day's point, for a series. */
 export interface PriceIndexDailyPoint {
     id: string;
@@ -94,6 +146,23 @@ export declare const PRICE_INDEX_MIN_CONFIDENT_SAMPLES = 3;
 export declare class PriceIndexRepository extends BaseRepository<PriceIndexDocument> {
     constructor();
     getForLeaf(leafId: string): Promise<PriceIndexDocument | null>;
+    /**
+     * Bands for several leaves in ONE round trip.
+     *
+     * 🛑 `db.getAll`, not N `findById` calls. The search tool resolves a query to
+     * up to 8 candidate leaves and needs a band for each; eight sequential reads
+     * is eight round trips against the ~3 Rule #6 budgets for a request, and it
+     * is the exact shape `storeAnalytics.ts:94` is cited as the pattern NOT to
+     * copy. `deriveTaxonomy`'s ancestor resolution made the same call for the
+     * same reason.
+     *
+     * 🛑 A missing document is OMITTED from the map, never returned as an empty
+     * band. A leaf with no completed sales must render "no sales recorded yet",
+     * and a zeroed band would render "₹0" — a confident, wrong figure, which is
+     * the failure mode the whole index is written to avoid (`market` vs `sold`,
+     * never blended, never zeroed).
+     */
+    getManyForLeaves(leafIds: readonly string[]): Promise<Map<string, PriceIndexDocument>>;
     /**
      * Write the current band for one leaf.
      *

package/dist/features/categories/repository/price-index.repository.js

@@ -30,7 +30,7 @@
  * already carries two unbounded arrays and a third is the 1 MiB trap. The
  * samples stay in job memory and only the summary is written.
  */
-import { BaseRepository } from "../../../providers/db-firebase";
+import { BaseRepository } from "../../../providers/db-firebase/index.js";
 export const PRICE_INDEX_COLLECTION = "priceIndex";
 const DAILY_SUBCOLLECTION = "daily";
 /**
@@ -48,6 +48,36 @@ export class PriceIndexRepository extends BaseRepository {
     async getForLeaf(leafId) {
         return this.findById(leafId);
     }
+    /**
+     * Bands for several leaves in ONE round trip.
+     *
+     * 🛑 `db.getAll`, not N `findById` calls. The search tool resolves a query to
+     * up to 8 candidate leaves and needs a band for each; eight sequential reads
+     * is eight round trips against the ~3 Rule #6 budgets for a request, and it
+     * is the exact shape `storeAnalytics.ts:94` is cited as the pattern NOT to
+     * copy. `deriveTaxonomy`'s ancestor resolution made the same call for the
+     * same reason.
+     *
+     * 🛑 A missing document is OMITTED from the map, never returned as an empty
+     * band. A leaf with no completed sales must render "no sales recorded yet",
+     * and a zeroed band would render "₹0" — a confident, wrong figure, which is
+     * the failure mode the whole index is written to avoid (`market` vs `sold`,
+     * never blended, never zeroed).
+     */
+    async getManyForLeaves(leafIds) {
+        const ids = [...new Set(leafIds.filter(Boolean))];
+        const out = new Map();
+        if (ids.length === 0)
+            return out;
+        const refs = ids.map((id) => this.db.collection(PRICE_INDEX_COLLECTION).doc(id));
+        const snaps = await this.db.getAll(...refs);
+        for (const snap of snaps) {
+            if (!snap.exists)
+                continue;
+            out.set(snap.id, { ...snap.data(), id: snap.id });
+        }
+        return out;
+    }
     /**
      * Write the current band for one leaf.
      *

package/dist/features/categories/schemas/bundle-form.js

@@ -35,9 +35,9 @@
  * @tag sideEffects:none
  */
 import { z } from "zod";
-import { annotate } from "../../shell/field-ui-meta";
-import { BUNDLE_COPY } from "../../../_internal/shared/features/categories/bundle-copy";
-import { BUNDLE_MIN_ITEMS, BUNDLE_MAX_ITEMS, } from "../../../_internal/shared/features/categories/bundle-config";
+import { annotate } from "../../shell/field-ui-meta.js";
+import { BUNDLE_COPY } from "../../../_internal/shared/features/categories/bundle-copy.js";
+import { BUNDLE_MIN_ITEMS, BUNDLE_MAX_ITEMS, } from "../../../_internal/shared/features/categories/bundle-config.js";
 /** The two member sources, as the rule-type select offers them. */
 export const BUNDLE_RULE_TYPE_OPTIONS = [
     { value: "static", label: BUNDLE_COPY.adminEditor.ruleTypeStatic },

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

@@ -0,0 +1,155 @@
+/**
+ * G3b — LISTING COUNTS, maintained incrementally leaf→root.
+ *
+ * 🛑 WHY THIS IS A SIBLING COLLECTION AND NOT A FIELD ON `categories`.
+ *
+ * `handleCategoryWrite` calls `notifyRevalidate({ collection: "categories" })`
+ * as its FIRST statement, unconditionally, before any branch — so ANY write to
+ * a category document drops that category page's ISR entry. Under leaf→root,
+ * publishing one listing touches up to five ancestors, so it would drop five
+ * ISR entries per publish. This project was paused with **ISR writes at 3.1M
+ * against a 200K cap (15.5×)**, which settles the question.
+ *
+ * It also removes the Root Cause #92 hazard outright: a trigger that writes
+ * back to the collection it watches produced 1,017,548 invocations in 24 hours
+ * and a billing denial that blocked `firebase deploy`.
+ *
+ * 🛑 AND `metrics.*` ON `categories` STAYS — a constraint the plan did not
+ * record. Two Sieve SORTS order by `metrics.productCount` through Firestore
+ * (`CategoriesIndexListing`'s "Most Products" and
+ * `AdminSublistingCategoriesView`'s "Most listings"), and a sibling collection
+ * cannot serve an `orderBy` on the categories query. So:
+ *
+ *   - `metrics.*`      — written ONLY by the nightly `countersReconcile`, as
+ *                        today. The two sorts keep working at exactly today's
+ *                        accuracy, so there is no regression, and the ISR cost
+ *                        is unchanged from the status quo (one drop per
+ *                        category per night, already happening).
+ *   - `categoryCounts` — the LIVE value, written per product mutation. Fires no
+ *                        revalidation, because nothing triggers on it.
+ *
+ * Readers prefer `categoryCounts` and fall back to `metrics`. That ordering is
+ * what makes the feature additive: a category with no counts document yet
+ * renders exactly as it does today rather than as zero.
+ *
+ * 🛑 HOW FRESH IT ACTUALLY IS, stated precisely rather than as "live".
+ *
+ * The count is of AVAILABLE rows — `isListingRowAvailable`, the same predicate
+ * `countersReconcile` and the listing query use. That predicate is partly
+ * TIME-dependent: `auction` is the one type with an inequality clause
+ * (`auctionEndDate`), so an auction becomes unavailable by the clock with no
+ * product write, and no incremental counter can observe that.
+ *
+ * In practice the window is minutes, not a day: `auctionSettlement` writes
+ * `isSold: true` when it settles, and that write re-evaluates the counter.
+ * Every other type's unavailability is write-driven (stock, `isSold`,
+ * `digitalCode.codesAvailable`, the prize-draw reveal status).
+ *
+ * So: instant for every write-driven change, and bounded by the settlement
+ * cadence for a just-ended auction. That is strictly better than today, where
+ * every change is up to 24h stale. The nightly reconciler stays as the
+ * authority and the audit — its `drifted` counter becomes a real signal that
+ * an increment was missed.
+ */
+import type { ListingType } from "../../products/types";
+export declare const CATEGORY_COUNTS_COLLECTION = "categoryCounts";
+/**
+ * Per-listing-type counters.
+ *
+ * 🛑 `Partial` on purpose: an absent key means "zero observed". Writing nine
+ * explicit zeros on every row is noise, and it would also make an untouched
+ * category indistinguishable from one measured as empty.
+ *
+ * A MAP rather than scalar fields, because own+total across nine listing types
+ * is 18 fields that grow with the union — and the union has grown twice
+ * already. A map needs no schema change for a tenth type.
+ */
+export type ListingTypeCounts = Partial<Record<ListingType, number>>;
+/**
+ * 🛑 THE INVARIANT, and the one way to get this wrong:
+ *
+ *     total  =  own  +  (every descendant's own)
+ *
+ * **`total` ALREADY INCLUDES `own`. Never add them.** `own + total` double-counts
+ * every item filed directly under the row, and on a leaf — where `total === own`
+ * — it doubles the whole number.
+ *
+ * So there are three questions and only two stored fields, because the third is
+ * a subtraction and a stored mirror of it would drift the first time one half
+ * was written without the other (Root Cause #42):
+ *
+ * | Question | Read |
+ * |---|---|
+ * | "how many are filed right here?" | `own` |
+ * | "how many are under my subcategories?" | **`descendantCountsFor()`** — `total − own`, derived |
+ * | "how many will clicking this show me?" | `total` |
+ *
+ * The third is the one a buyer means, which is why `liveTotalFor` returns it
+ * and why the category chips and grid read it. The second exists because the
+ * distinction is genuinely useful to an admin — `CategoryTableColumns` already
+ * renders "own (total)" explicitly — and because deriving it is the only way to
+ * show it without a third counter to keep in step.
+ */
+export interface CategoryCountsDocument {
+    /** === the category's document id. */
+    id: string;
+    /** Listings filed DIRECTLY under this category, by type. */
+    own: ListingTypeCounts;
+    /**
+     * Own + every descendant's, by type. Equals `own` on a leaf.
+     *
+     * 🛑 INCLUDES `own` — see the invariant above. Never `own + total`.
+     */
+    total: ListingTypeCounts;
+    /**
+     * Multi-item LOTS, counted separately from singles.
+     *
+     * 🛑 This separation is what makes a count mean one thing, and it is why the
+     * filing rule in `deriveTaxonomy` only has to refuse a lot at a LEAF rather
+     * than also refusing a single at a non-leaf. A lot and a single are never
+     * summed into one number, so "12 listings here" is unambiguous wherever they
+     * are filed. (Measured: 58 of 70 live products file at a non-leaf, so the
+     * symmetric rule the plan first specified would have rejected most of the
+     * catalogue — see the `isLot` docstring on `ProductDocument`.)
+     *
+     * Scalars rather than a per-type map: a lot is not type-specific in any way
+     * a buyer or a seller filters on, and there is no reader for "lots of
+     * auctions".
+     */
+    lots: {
+        own: number;
+        total: number;
+    };
+    updatedAt: Date;
+}
+/** Sum a counts map — what a category page renders as "N listings". */
+export declare function sumCounts(counts: ListingTypeCounts | undefined): number;
+/**
+ * The display count for a category, preferring the live document.
+ *
+ * 🛑 `undefined` means "no counts document yet", NOT zero — so the caller falls
+ * back to `metrics`. Returning 0 here would render a confident zero on every
+ * category until the first mutation, which is Root Cause #72's lesson (a count
+ * that failed must never be indistinguishable from a count of nothing).
+ */
+export declare function liveTotalFor(doc: Pick<CategoryCountsDocument, "total" | "lots"> | null | undefined): number | undefined;
+/** Filed directly here, lots included. The "N here" half of "N here, M below". */
+export declare function ownTotalFor(doc: Pick<CategoryCountsDocument, "own" | "lots"> | null | undefined): number | undefined;
+/**
+ * How many sit under this row's DESCENDANTS and not directly on it — `total − own`.
+ *
+ * 🛑 DERIVED, never stored, and that is the point: a third stored counter would
+ * be a mirror of a subtraction, and a mirror drifts the moment one half is
+ * written without the other (Root Cause #42). It is also the function that
+ * makes the invariant un-missable — anyone reaching for "own plus children"
+ * finds this instead of writing `own + total`, which double-counts every item
+ * filed directly on the row.
+ *
+ * Clamped at 0. A negative value is real and means the counters drifted (an
+ * increment lost between the leaf write and an ancestor's), and surfacing
+ * "−3 in subcategories" to a visitor is worse than showing none — the nightly
+ * reconciler's `countsWritten` is where that drift is meant to be seen.
+ */
+export declare function descendantTotalFor(doc: Pick<CategoryCountsDocument, "own" | "total" | "lots"> | null | undefined): number | undefined;
+/** The per-type descendant split, same derivation and the same clamp. */
+export declare function descendantCountsFor(doc: Pick<CategoryCountsDocument, "own" | "total"> | null | undefined): ListingTypeCounts | undefined;

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

@@ -0,0 +1,116 @@
+/**
+ * G3b — LISTING COUNTS, maintained incrementally leaf→root.
+ *
+ * 🛑 WHY THIS IS A SIBLING COLLECTION AND NOT A FIELD ON `categories`.
+ *
+ * `handleCategoryWrite` calls `notifyRevalidate({ collection: "categories" })`
+ * as its FIRST statement, unconditionally, before any branch — so ANY write to
+ * a category document drops that category page's ISR entry. Under leaf→root,
+ * publishing one listing touches up to five ancestors, so it would drop five
+ * ISR entries per publish. This project was paused with **ISR writes at 3.1M
+ * against a 200K cap (15.5×)**, which settles the question.
+ *
+ * It also removes the Root Cause #92 hazard outright: a trigger that writes
+ * back to the collection it watches produced 1,017,548 invocations in 24 hours
+ * and a billing denial that blocked `firebase deploy`.
+ *
+ * 🛑 AND `metrics.*` ON `categories` STAYS — a constraint the plan did not
+ * record. Two Sieve SORTS order by `metrics.productCount` through Firestore
+ * (`CategoriesIndexListing`'s "Most Products" and
+ * `AdminSublistingCategoriesView`'s "Most listings"), and a sibling collection
+ * cannot serve an `orderBy` on the categories query. So:
+ *
+ *   - `metrics.*`      — written ONLY by the nightly `countersReconcile`, as
+ *                        today. The two sorts keep working at exactly today's
+ *                        accuracy, so there is no regression, and the ISR cost
+ *                        is unchanged from the status quo (one drop per
+ *                        category per night, already happening).
+ *   - `categoryCounts` — the LIVE value, written per product mutation. Fires no
+ *                        revalidation, because nothing triggers on it.
+ *
+ * Readers prefer `categoryCounts` and fall back to `metrics`. That ordering is
+ * what makes the feature additive: a category with no counts document yet
+ * renders exactly as it does today rather than as zero.
+ *
+ * 🛑 HOW FRESH IT ACTUALLY IS, stated precisely rather than as "live".
+ *
+ * The count is of AVAILABLE rows — `isListingRowAvailable`, the same predicate
+ * `countersReconcile` and the listing query use. That predicate is partly
+ * TIME-dependent: `auction` is the one type with an inequality clause
+ * (`auctionEndDate`), so an auction becomes unavailable by the clock with no
+ * product write, and no incremental counter can observe that.
+ *
+ * In practice the window is minutes, not a day: `auctionSettlement` writes
+ * `isSold: true` when it settles, and that write re-evaluates the counter.
+ * Every other type's unavailability is write-driven (stock, `isSold`,
+ * `digitalCode.codesAvailable`, the prize-draw reveal status).
+ *
+ * So: instant for every write-driven change, and bounded by the settlement
+ * cadence for a just-ended auction. That is strictly better than today, where
+ * every change is up to 24h stale. The nightly reconciler stays as the
+ * authority and the audit — its `drifted` counter becomes a real signal that
+ * an increment was missed.
+ */
+export const CATEGORY_COUNTS_COLLECTION = "categoryCounts";
+/** Sum a counts map — what a category page renders as "N listings". */
+export function sumCounts(counts) {
+    if (!counts)
+        return 0;
+    let n = 0;
+    for (const v of Object.values(counts))
+        n += v ?? 0;
+    return n;
+}
+/**
+ * The display count for a category, preferring the live document.
+ *
+ * 🛑 `undefined` means "no counts document yet", NOT zero — so the caller falls
+ * back to `metrics`. Returning 0 here would render a confident zero on every
+ * category until the first mutation, which is Root Cause #72's lesson (a count
+ * that failed must never be indistinguishable from a count of nothing).
+ */
+export function liveTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    return sumCounts(doc.total) + (doc.lots?.total ?? 0);
+}
+/** Filed directly here, lots included. The "N here" half of "N here, M below". */
+export function ownTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    return sumCounts(doc.own) + (doc.lots?.own ?? 0);
+}
+/**
+ * How many sit under this row's DESCENDANTS and not directly on it — `total − own`.
+ *
+ * 🛑 DERIVED, never stored, and that is the point: a third stored counter would
+ * be a mirror of a subtraction, and a mirror drifts the moment one half is
+ * written without the other (Root Cause #42). It is also the function that
+ * makes the invariant un-missable — anyone reaching for "own plus children"
+ * finds this instead of writing `own + total`, which double-counts every item
+ * filed directly on the row.
+ *
+ * Clamped at 0. A negative value is real and means the counters drifted (an
+ * increment lost between the leaf write and an ancestor's), and surfacing
+ * "−3 in subcategories" to a visitor is worse than showing none — the nightly
+ * reconciler's `countsWritten` is where that drift is meant to be seen.
+ */
+export function descendantTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    const total = liveTotalFor(doc) ?? 0;
+    const own = ownTotalFor(doc) ?? 0;
+    return Math.max(0, total - own);
+}
+/** The per-type descendant split, same derivation and the same clamp. */
+export function descendantCountsFor(doc) {
+    if (!doc)
+        return undefined;
+    const out = {};
+    for (const k of Object.keys(doc.total ?? {})) {
+        const d = (doc.total[k] ?? 0) - (doc.own?.[k] ?? 0);
+        if (d > 0)
+            out[k] = d;
+    }
+    return out;
+}

package/dist/features/categories/schemas/firestore.d.ts

@@ -108,7 +108,6 @@ export interface CategoryDocument extends BaseDocument {
      */
     subtreeSize: number;
     metrics: CategoryDocumentMetrics;
-    viewCount?: number;
     isFeatured: boolean;
     featuredPriority?: number;
     /** @deprecated Use categoryType === "brand". Will be removed once seed + admin form fully migrate. */
@@ -329,7 +328,6 @@ export declare const CATEGORY_FIELDS: {
     readonly FEATURED_PRIORITY: "featuredPriority";
     readonly SEO: "seo";
     readonly DISPLAY: "display";
-    readonly VIEW_COUNT: "viewCount";
     readonly IS_ACTIVE: "isActive";
     readonly IS_SEARCHABLE: "isSearchable";
     readonly SEARCH_TXT: "searchTxt";