@mohasinac/appkit 4.43.0 → 4.45.0

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

@@ -1,10 +1,14 @@
 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 } from "@mohasinac/appkit";
+import type { FirestoreDocument, JsonValue } from "@mohasinac/appkit";
 export declare class CategoriesRepository extends BaseRepository<CategoryDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
-    list(model: SieveModel): Promise<FirebaseSieveResult<CategoryDocument>>;
+    /** Derived on every write path via `applyWriteHooks`. */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    list(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<CategoryDocument>>;
     createWithHierarchy(input: CategoryCreateInput): Promise<CategoryDocument>;
     getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
     getRootCategories(): Promise<CategoryDocument[]>;
@@ -20,16 +24,64 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * caller still slices to its own limit.
      */
     getCategoriesByTier(tier: number, limit?: number): Promise<CategoryDocument[]>;
-    getCategoriesByRootId(rootId: string): Promise<CategoryDocument[]>;
-    getChildren(parentId: string): Promise<CategoryDocument[]>;
     /**
-     * IDs of every descendant category at any depth (not just direct
-     * children) — `parentIds` stores the full ancestor chain, so a single
-     * array-contains query on that field already returns the whole subtree
-     * with no recursion needed. Used to expand a parent category's product
-     * listing/count to include products filed under any of its children.
+     * Every category sharing a root, tier-then-order.
+     *
+     * 🛑 `limit` is for DISPLAY callers only, and it is a real truncation.
+     * `buildTree(rootId)` must pass nothing: a tree built from a truncated node
+     * list silently drops whole branches, which is the exact failure
+     * `getDescendants`'s docstring was rewritten to avoid. A display grid of
+     * sibling categories, by contrast, renders ~20 tiles and has no reason to
+     * read 1,500 documents to do it.
+     *
+     * Paginated rather than one unbounded `.get()`: the previous form read the
+     * whole root subtree into memory on every category page render, which at the
+     * ~330-node forest this plan seeds is ~9% of a 50K/day Firestore budget for
+     * ONE page view.
+     */
+    /**
+     * Several categories by id, in ONE round trip, in the order asked for.
+     *
+     * The ancestor-walk primitive. A five-tier tree means a leaf has up to four
+     * ancestors, and resolving an inherited description template or an inherited
+     * `productDefaults` means reading them nearest-first until the answer is
+     * found — which as four sequential `findById` calls is four round trips, on
+     * a route the seller form hits on every category change. Rule #6 budgets
+     * about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled. Callers
+     * walk the result looking for the first document that declares a thing, so
+     * "nearest first" has to survive the round trip — Firestore's `getAll`
+     * already answers in argument order, and this keeps that guarantee explicit
+     * rather than incidental. A caller needing to know WHICH id was missing
+     * should compare lengths; none does, because an ancestor that no longer
+     * exists is a data problem for the reconcile job, not a reason to fail a
+     * form.
+     *
+     * Bounded at 30 to match `array-contains-any`'s cap, so this cannot become
+     * the unbounded read that `getCategoriesByRootId` had to be rewritten to
+     * avoid being.
      */
-    getDescendantIds(categoryId: string): Promise<string[]>;
+    findByIds(ids: string[]): Promise<CategoryDocument[]>;
+    getCategoriesByRootId(rootId: string, opts?: {
+        limit?: number;
+    }): Promise<CategoryDocument[]>;
+    /**
+     * Categories whose `productDefaults.taxCodeId` points at `taxCodeId`.
+     *
+     * 🛑 Exists so DELETE on a tax code can REFUSE while it is referenced.
+     * `taxCodeId` is a plain string with no referential integrity, and a
+     * dangling reference does not error — `findResolvable` answers `null`,
+     * whose correct handling is "leave the product's gstRate alone", so every
+     * subsequent listing under that category silently derives NO TAX. It does
+     * not fail; it under-charges, until someone reads an invoice.
+     *
+     * One equality on a dot-path — served by the automatic index, no composite
+     * to declare. Bounded at 200: the answer is used to NAME referrers in a 409
+     * message, and the first five are what the admin reads.
+     */
+    findByTaxCodeId(taxCodeId: string): Promise<CategoryDocument[]>;
+    getChildren(parentId: string): Promise<CategoryDocument[]>;
     /**
      * Every descendant DOCUMENT at any depth.
      *
@@ -169,7 +221,6 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * SB-UNI-B — derive the canonical `sublisting-{slug}` ID from a
      * human-entered category name.
      */
-    incrementViewCount(categoryId: string): Promise<void>;
     generateSublistingId(name: string): string;
 }
 export declare const categoriesRepository: CategoriesRepository;

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

@@ -1,15 +1,45 @@
-import { normalizeError } from "../../../errors/normalize";
-import { increment, arrayUnion, arrayRemove, } from "../../../contracts/field-ops";
-import { DatabaseError } from "../../../errors";
-import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
-import { PRODUCT_FIELDS } from "../../../constants/field-names";
-import { CATEGORY_FIELDS, CATEGORIES_COLLECTION, MIN_ITEMS_FOR_FEATURED, buildCategoryTree, calculateCategoryFields, canBeFeatured, createCategoryId, isValidCategoryMove, } from "../schemas";
+import { normalizeError } from "../../../errors/normalize.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";
+import { buildCategorySearchTxt } from "../../../utils/search-txt-builders.js";
+import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query.js";
+import { PRODUCT_FIELDS } from "../../../constants/field-names.js";
+import { CATEGORY_FIELDS, CATEGORIES_COLLECTION, MIN_ITEMS_FOR_FEATURED, buildCategoryTree, calculateCategoryFields, canBeFeatured, createCategoryId, isValidCategoryMove, } from "../schemas/index.js";
 export class CategoriesRepository extends BaseRepository {
     constructor() {
         super(CATEGORIES_COLLECTION);
     }
-    async list(model) {
-        return this.sieveQuery(model, CategoriesRepository.SIEVE_FIELDS);
+    /** Derived on every write path via `applyWriteHooks`. */
+    buildSearchTxtFor(data) {
+        return buildCategorySearchTxt(data);
+    }
+    async list(model, opts) {
+        /*
+         * `q` is a searchTxt pushdown, NOT a Sieve filter.
+         *
+         * `plan.head` becomes one `array-contains` on the longest term and
+         * `plan.rest` is AND-refined in memory — the same two-part shape the other
+         * ten migrated collections use. Going through `planSearchTxt` rather than
+         * hand-rolling it is what buys the `empty` guard: a query that normalises
+         * to no usable token (`"!!!"`, `"—"`) must return NOTHING, because
+         * emitting no clause at all returns the whole collection and calls it a
+         * search result. That is the live bug `products` still has (A2).
+         */
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        if (!plan.head) {
+            return this.sieveQuery(model, CategoriesRepository.SIEVE_FIELDS);
+        }
+        const baseQuery = this.getCollection().where(CATEGORY_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        const result = await applySieveToFirestore({
+            baseQuery,
+            model,
+            fields: CategoriesRepository.SIEVE_FIELDS,
+            mapDoc: (snap) => this.mapDoc(snap),
+        });
+        return refineSearchTxt(result, plan.rest);
     }
     async createWithHierarchy(input) {
         try {
@@ -141,21 +171,139 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve categories by tier: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    async getCategoriesByRootId(rootId) {
+    /**
+     * Every category sharing a root, tier-then-order.
+     *
+     * 🛑 `limit` is for DISPLAY callers only, and it is a real truncation.
+     * `buildTree(rootId)` must pass nothing: a tree built from a truncated node
+     * list silently drops whole branches, which is the exact failure
+     * `getDescendants`'s docstring was rewritten to avoid. A display grid of
+     * sibling categories, by contrast, renders ~20 tiles and has no reason to
+     * read 1,500 documents to do it.
+     *
+     * Paginated rather than one unbounded `.get()`: the previous form read the
+     * whole root subtree into memory on every category page render, which at the
+     * ~330-node forest this plan seeds is ~9% of a 50K/day Firestore budget for
+     * ONE page view.
+     */
+    /**
+     * Several categories by id, in ONE round trip, in the order asked for.
+     *
+     * The ancestor-walk primitive. A five-tier tree means a leaf has up to four
+     * ancestors, and resolving an inherited description template or an inherited
+     * `productDefaults` means reading them nearest-first until the answer is
+     * found — which as four sequential `findById` calls is four round trips, on
+     * a route the seller form hits on every category change. Rule #6 budgets
+     * about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled. Callers
+     * walk the result looking for the first document that declares a thing, so
+     * "nearest first" has to survive the round trip — Firestore's `getAll`
+     * already answers in argument order, and this keeps that guarantee explicit
+     * rather than incidental. A caller needing to know WHICH id was missing
+     * should compare lengths; none does, because an ancestor that no longer
+     * exists is a data problem for the reconcile job, not a reason to fail a
+     * form.
+     *
+     * Bounded at 30 to match `array-contains-any`'s cap, so this cannot become
+     * the unbounded read that `getCategoriesByRootId` had to be rewritten to
+     * avoid being.
+     */
+    async findByIds(ids) {
+        const unique = Array.from(new Set(ids.filter(Boolean))).slice(0, 30);
+        if (unique.length === 0)
+            return [];
         try {
-            const snapshot = await this.db
-                .collection(this.collection)
-                .where(CATEGORY_FIELDS.ROOT_ID, "==", rootId)
-                .orderBy(CATEGORY_FIELDS.TIER, "asc")
-                .orderBy(CATEGORY_FIELDS.ORDER, "asc")
-                .get();
-            return snapshot.docs.map((doc) => this.mapDoc(doc));
+            const refs = unique.map((id) => this.db.collection(this.collection).doc(id));
+            const snaps = await this.db.getAll(...refs);
+            return snaps
+                .filter((s) => s.exists)
+                .map((s) => this.mapDoc(s));
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            /*
+             * 🛑 The raw `.message` is NOT interpolated into the thrown error — only
+             * the normalised `kind` and a count.
+             *
+             * Several older methods in this file do interpolate it, and
+             * `audit-raw-error-text` flagged this one for trying. The reasoning is
+             * Root Cause #86's: a thrown value's message is written for a developer,
+             * and this one reaches a user through the route's 500 branch — which is
+             * how a Node `MODULE_NOT_FOUND` with a full require stack ended up
+             * rendered inside the "Place your bid" modal.
+             *
+             * The ids are counted rather than listed. A category id is not
+             * sensitive, but 30 of them in one line is noise against Hobby's ~4 KB/s
+             * log budget.
+             *
+             * (`normalizeError` has to be the FIRST statement, not merely nearby:
+             * `audit-catch-normalize` looks within a few lines of the catch, and the
+             * first draft put this comment above the call and tripped it.)
+             */
+            throw new DatabaseError(`Failed to read categories by id (${unique.length} requested): ${e.kind}`);
+        }
+    }
+    async getCategoriesByRootId(rootId, opts) {
+        try {
+            const cap = opts?.limit;
+            const pageSize = cap ? Math.min(cap, 300) : 300;
+            const out = [];
+            let cursor = null;
+            for (;;) {
+                let q = this.db
+                    .collection(this.collection)
+                    .where(CATEGORY_FIELDS.ROOT_ID, "==", rootId)
+                    .orderBy(CATEGORY_FIELDS.TIER, "asc")
+                    .orderBy(CATEGORY_FIELDS.ORDER, "asc")
+                    .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 (cap && out.length >= cap)
+                    return out.slice(0, cap);
+                if (page.size < pageSize)
+                    break;
+                cursor = page.docs[page.docs.length - 1];
+            }
+            return out;
         }
         catch (error) {
             void normalizeError(error);
             throw new DatabaseError(`Failed to retrieve categories by rootId: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * Categories whose `productDefaults.taxCodeId` points at `taxCodeId`.
+     *
+     * 🛑 Exists so DELETE on a tax code can REFUSE while it is referenced.
+     * `taxCodeId` is a plain string with no referential integrity, and a
+     * dangling reference does not error — `findResolvable` answers `null`,
+     * whose correct handling is "leave the product's gstRate alone", so every
+     * subsequent listing under that category silently derives NO TAX. It does
+     * not fail; it under-charges, until someone reads an invoice.
+     *
+     * One equality on a dot-path — served by the automatic index, no composite
+     * to declare. Bounded at 200: the answer is used to NAME referrers in a 409
+     * message, and the first five are what the admin reads.
+     */
+    async findByTaxCodeId(taxCodeId) {
+        try {
+            const snap = await this.getCollection()
+                .where(CATEGORY_FIELDS.PRODUCT_DEFAULTS_TAX_CODE_ID, "==", taxCodeId)
+                .limit(200)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to find categories by tax code: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
     async getChildren(parentId) {
         try {
             const snapshot = await this.db
@@ -173,17 +321,16 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve children categories: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    /**
-     * IDs of every descendant category at any depth (not just direct
-     * children) — `parentIds` stores the full ancestor chain, so a single
-     * array-contains query on that field already returns the whole subtree
-     * with no recursion needed. Used to expand a parent category's product
-     * listing/count to include products filed under any of its children.
+    /*
+     * 🛑 `getDescendantIds` was DELETED (2026-10-10). It was
+     * `getDescendants(id).then(d => d.map(x => x.id))`, and its only caller —
+     * CategoryDetailPageView — already held the documents from its own
+     * `getDescendants` call in the same render. So it re-ran the identical
+     * paginated subtree query and discarded everything but the ids: ~330 wasted
+     * reads per page view at the forest size this plan seeds, and two answers
+     * that could disagree whenever one read failed and the other did not.
+     * Call `getDescendants` and `.map(d => d.id)` at the one site that needs it.
      */
-    async getDescendantIds(categoryId) {
-        const docs = await this.getDescendants(categoryId);
-        return docs.map((d) => d.id);
-    }
     /**
      * Every descendant DOCUMENT at any depth.
      *
@@ -696,24 +843,19 @@ export class CategoriesRepository extends BaseRepository {
             .get();
         return snap.docs.map((d) => this.mapDoc(d));
     }
+    /*
+     * 🛑 `incrementViewCount` DELETED 2026-10-10 — zero callers since
+     * 2026-08-31, when it was removed from the category-detail render path (a
+     * Firestore write per render, and a second counter racing `pageViews`).
+     *
+     * Measured: `viewCount` is absent from all 58 category documents. Deleting
+     * the writer nobody calls is what stops the dead field reading as live. See
+     * the products repository for the same removal.
+     */
     /**
      * SB-UNI-B — derive the canonical `sublisting-{slug}` ID from a
      * human-entered category name.
      */
-    async incrementViewCount(categoryId) {
-        try {
-            await this.db
-                .collection(this.collection)
-                .doc(categoryId)
-                .update({ [CATEGORY_FIELDS.VIEW_COUNT]: increment(1) });
-            // Fire-and-forget analytics: a lost view increment changes nothing that
-            // renders, so it must never break the category read path it rides along
-            // with — the count is approximate by design.
-        }
-        catch (_err) {
-            void normalizeError(_err);
-        }
-    }
     generateSublistingId(name) {
         const base = name
             .toLowerCase()
@@ -730,6 +872,7 @@ CategoriesRepository.SIEVE_FIELDS = {
     isActive: { canFilter: true, canSort: false },
     isFeatured: { canFilter: true, canSort: false },
     isBrand: { canFilter: true, canSort: false },
+    searchTxt: { canFilter: true, canSort: false },
     categoryType: { canFilter: true, canSort: false },
     isSearchable: { canFilter: true, canSort: false },
     parentId: { canFilter: true, canSort: false, path: "parentIds" },

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

@@ -0,0 +1,184 @@
+/**
+ * Price Index Repository — what things actually SOLD for here, per leaf.
+ *
+ * ## 🛑 Why this is its own collection and not a field on `categories`
+ *
+ * The obvious design is `categories/{leafId}.productDefaults.priceGuidance.sold`,
+ * beside the seed-owned `market` band it is shown next to. That design is a
+ * runaway-trigger hazard and it is not a theoretical one.
+ *
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a price band there re-triggers it once per document. That is exactly
+ * the shape of Root Cause #92, where `onShipmentHeaderWrite` wrote back to the
+ * collection it watched and produced **1,017,548 invocations in 24 hours**
+ * against a 2M/month allowance, blocked `firebase deploy` with a billing
+ * denial, and degraded production.
+ *
+ * It is also worse than that here, because `notifyRevalidate` fires on every
+ * category write — so each nightly price write would drop that category page's
+ * ISR entry, on a project that was paused for exceeding ISR writes by 15.5×.
+ *
+ * A sibling collection removes the self-write entirely. It costs one extra
+ * read on the surface that shows the band, and buys immunity.
+ *
+ * ## Shape
+ *
+ *   priceIndex/{leafId}                 the current band
+ *   priceIndex/{leafId}/daily/{YYYYMMDD}  one point per day, for a series
+ *
+ * 🛑 NO `soldPrices: number[]` on the document. `CategoryDocument.metrics`
+ * 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";
+/** Which acquisition path a sale came through. Counts, not amounts. */
+export interface PriceIndexByPath {
+    standard?: number;
+    auction?: number;
+    offer?: number;
+}
+export interface PriceIndexDocument {
+    /** The LEAF category id. A sale rolls up to exactly one leaf. */
+    id: string;
+    currency: "INR";
+    /**
+     * Scoped by listing type WITHIN the leaf.
+     *
+     * 🛑 Load-bearing. A named-model leaf holds every listing type for that
+     * model — the bey, its stickers, its spare parts, a used one as a classified
+     * — because `listingType` and `categorySlugs` are independent axes. A ₹399
+     * sticker sheet and a ₹1,299 bey under one leaf would blend into a
+     * meaningless band, so the band is per type and the UI shows the one the
+     * seller is listing.
+     */
+    byListingType: Record<string, PriceIndexBand>;
+    /** How many days of completed sales the bands cover. */
+    windowDays: number;
+    computedAt: Date;
+}
+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`
+     * rendering "50+" rather than a false total. A median of two sales is a coin
+     * flip presented as data.
+     */
+    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;
+    /** `YYYYMMDD`, so the document id sorts chronologically on its own. */
+    date: string;
+    byListingType: Record<string, Pick<PriceIndexBand, "median" | "sampleSize">>;
+    computedAt: Date;
+}
+export declare const PRICE_INDEX_COLLECTION = "priceIndex";
+/**
+ * Below this, a band renders as a sample size and no headline figure.
+ *
+ * Exported because the renderer and the job must agree: a threshold the job
+ * applied and the UI did not would hide bands that exist, and the reverse
+ * would publish a median of one sale as a market rate.
+ */
+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.
+     *
+     * `createWithId`/`update` rather than a blind `set`, matching every other
+     * rollup repository here — and `update` merges, so a leaf whose band for one
+     * listing type disappeared this run would keep the stale entry. Hence
+     * `byListingType` is replaced wholesale by passing the full map.
+     */
+    setForLeaf(leafId: string, data: Pick<PriceIndexDocument, "byListingType" | "windowDays">): Promise<void>;
+    /**
+     * Append today's point.
+     *
+     * Keyed on the date, so a re-run on the same day OVERWRITES rather than
+     * double-counting — the same idempotency `pageViewRollup`'s `throughDate`
+     * buys, achieved here by the document id instead of a cursor.
+     */
+    setDailyPoint(leafId: string, date: string, byListingType: PriceIndexDailyPoint["byListingType"]): Promise<void>;
+}
+export declare const priceIndexRepository: PriceIndexRepository;

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

@@ -0,0 +1,115 @@
+/**
+ * Price Index Repository — what things actually SOLD for here, per leaf.
+ *
+ * ## 🛑 Why this is its own collection and not a field on `categories`
+ *
+ * The obvious design is `categories/{leafId}.productDefaults.priceGuidance.sold`,
+ * beside the seed-owned `market` band it is shown next to. That design is a
+ * runaway-trigger hazard and it is not a theoretical one.
+ *
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a price band there re-triggers it once per document. That is exactly
+ * the shape of Root Cause #92, where `onShipmentHeaderWrite` wrote back to the
+ * collection it watched and produced **1,017,548 invocations in 24 hours**
+ * against a 2M/month allowance, blocked `firebase deploy` with a billing
+ * denial, and degraded production.
+ *
+ * It is also worse than that here, because `notifyRevalidate` fires on every
+ * category write — so each nightly price write would drop that category page's
+ * ISR entry, on a project that was paused for exceeding ISR writes by 15.5×.
+ *
+ * A sibling collection removes the self-write entirely. It costs one extra
+ * read on the surface that shows the band, and buys immunity.
+ *
+ * ## Shape
+ *
+ *   priceIndex/{leafId}                 the current band
+ *   priceIndex/{leafId}/daily/{YYYYMMDD}  one point per day, for a series
+ *
+ * 🛑 NO `soldPrices: number[]` on the document. `CategoryDocument.metrics`
+ * 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/index.js";
+export const PRICE_INDEX_COLLECTION = "priceIndex";
+const DAILY_SUBCOLLECTION = "daily";
+/**
+ * Below this, a band renders as a sample size and no headline figure.
+ *
+ * Exported because the renderer and the job must agree: a threshold the job
+ * applied and the UI did not would hide bands that exist, and the reverse
+ * would publish a median of one sale as a market rate.
+ */
+export const PRICE_INDEX_MIN_CONFIDENT_SAMPLES = 3;
+export class PriceIndexRepository extends BaseRepository {
+    constructor() {
+        super(PRICE_INDEX_COLLECTION);
+    }
+    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.
+     *
+     * `createWithId`/`update` rather than a blind `set`, matching every other
+     * rollup repository here — and `update` merges, so a leaf whose band for one
+     * listing type disappeared this run would keep the stale entry. Hence
+     * `byListingType` is replaced wholesale by passing the full map.
+     */
+    async setForLeaf(leafId, data) {
+        const payload = { currency: "INR", ...data, computedAt: new Date() };
+        const existing = await this.findById(leafId);
+        if (existing) {
+            await this.update(leafId, payload);
+        }
+        else {
+            await this.createWithId(leafId, payload);
+        }
+    }
+    /**
+     * Append today's point.
+     *
+     * Keyed on the date, so a re-run on the same day OVERWRITES rather than
+     * double-counting — the same idempotency `pageViewRollup`'s `throughDate`
+     * buys, achieved here by the document id instead of a cursor.
+     */
+    async setDailyPoint(leafId, date, byListingType) {
+        await this.db
+            .collection(PRICE_INDEX_COLLECTION)
+            .doc(leafId)
+            .collection(DAILY_SUBCOLLECTION)
+            .doc(date)
+            .set({ date, byListingType, computedAt: new Date() }, { merge: true });
+    }
+}
+export const priceIndexRepository = new PriceIndexRepository();