@mohasinac/appkit 4.44.0 → 4.46.0

package/dist/features/products/repository/products.repository.js

@@ -1,35 +1,44 @@
-import { normalizeError } from "../../../errors/normalize";
-import { increment, serverTimestamp } from "../../../contracts/field-ops";
-import { DatabaseError } from "../../../errors";
-import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
-import { cacheManager } from "../../../core";
-import { serverLogger } from "../../../monitoring";
-import { generateUniqueId, slugify, generateBarcodeId } from "../../../utils";
-import { parseSearchTxtQuery } from "../../../utils/search-txt";
+import { normalizeError } from "../../../errors/normalize.js";
+import { increment, serverTimestamp } from "../../../contracts/field-ops.js";
+// 🛑 `../../../errors` re-exports the REAL ValidationError (errors/validation-error),
+// which is the one `mapToHttpError` instanceof-checks to produce a 400. The
+// unrelated same-named class under `_internal/shared/errors` falls through every
+// classified branch to a generic 500 — Root Cause #53.
+import { DatabaseError } from "../../../errors/index.js";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { cacheManager } from "../../../core/index.js";
+import { serverLogger } from "../../../monitoring/index.js";
+import { generateUniqueId, slugify, generateBarcodeId } from "../../../utils/index.js";
+import { parseSearchTxtQuery } from "../../../utils/search-txt.js";
 // The shared search plan/refine the other eleven migrated collections use.
 // `planSearchTxt` carries the `empty` guard that keeps a punctuation-only query
 // from returning the whole catalogue.
-import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query";
+import { planSearchTxt, SEARCH_REFINE_WINDOW, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query.js";
 // One definition of "which fields feed searchTxt", shared with the seed
 // wrapper. Three copies existed and two were missing the same three fields.
-import { buildProductSearchTxt } from "../../../utils/search-txt-builders";
-import { PRODUCT_COLLECTION, ProductStatusValues } from "../schemas";
+import { buildProductSearchTxt } from "../../../utils/search-txt-builders.js";
+import { PRODUCT_COLLECTION, ProductStatusValues } from "../schemas/index.js";
 // Collection NAMES only — deliberately not `categoriesRepository` or
 // `taxCodesRepository`. See deriveTaxonomy()'s header for why these are raw
 // reads: no repository in this codebase imports another feature's, because of
 // the Turbopack import-chain trap (Root Cause #6/#18).
-import { CATEGORIES_COLLECTION } from "../../categories/schemas/firestore";
-import { TAX_CODES_COLLECTION } from "../../tax-codes/schemas/firestore";
+import { CATEGORIES_COLLECTION } from "../../categories/schemas/firestore.js";
+import { CATEGORY_COUNTS_COLLECTION, sumCounts } from "../../categories/schemas/category-counts.js";
+import { ENFORCE_LEAF_FILING, assertAssignmentShape, buildTaxonomyClosure, pickDefaultAssignment, readAssignments, } from "./category-assignment.js";
+import { describeCountable, countsChanged, buildCountPatch, applyCountPatch, } from "../../categories/repository/category-counts.js";
+// The ONE availability predicate — never a second copy (Root Cause #73).
+import { isListingRowAvailable } from "../../../_internal/shared/listing-types/_registry.js";
+import { TAX_CODES_COLLECTION } from "../../tax-codes/schemas/firestore.js";
 // Collection id only, never the stores repository — no repository in this
 // codebase imports another feature's (the Turbopack import-chain trap).
-import { STORE_COLLECTION } from "../../stores/schemas/firestore";
+import { STORE_COLLECTION } from "../../stores/schemas/firestore.js";
 // Pure money math — no Firestore, no server-only imports.
-import { DEFAULT_GST_RATE, grossFromTaxable } from "../../../_internal/shared/fees/calculator";
-import { MAX_FEATURES_PER_PRODUCT } from "../schemas/product-features";
+import { DEFAULT_GST_RATE, grossFromTaxable } from "../../../_internal/shared/fees/calculator.js";
+import { MAX_FEATURES_PER_PRODUCT } from "../schemas/product-features.js";
 // The ONE `{{placeholder}}` implementation, promoted out of the FAQ schema in
 // B3. A second regex here would be Root Cause #75's shape.
-import { interpolate } from "../../../_internal/shared/templating/placeholders";
-import { PRODUCT_FIELDS } from "../../../constants/field-names";
+import { interpolate } from "../../../_internal/shared/templating/placeholders.js";
+import { PRODUCT_FIELDS } from "../../../constants/field-names.js";
 /**
  * Canonical listing-kind tokens used in `listingType`. Note: the public Sieve
  * alias accepts the legacy "preorder" / "product" spelling; we normalise to
@@ -103,6 +112,78 @@ function interpolateDefaults(template, input, derived) {
         siteName: "LetItRip",
     }).text;
 }
+/**
+ * Keep `availableQuantity` in step when a seller edits `stockQuantity`.
+ *
+ * 🛑 THE BUG THIS CLOSES: A SELLER COULD NOT RESTOCK.
+ *
+ * There are two stock numbers. `stockQuantity` is seller-authored and is the
+ * only one any of the three product forms exposes. `availableQuantity` is
+ * system-owned, seeded from `stockQuantity` **once, at create**, and
+ * thereafter driven by checkout decrements and timeout restores.
+ *
+ * Nothing re-synced them. `updateProduct` is a bare spread, and grep for
+ * `availableQuantity` across `src/app/api/store/products/**` and
+ * `seller-actions.ts` returns ZERO. So: a product sells out
+ * (`availableQuantity: 0`), the seller edits `stockQuantity` 0 → 10, and the
+ * product STAYS UNBUYABLE — purchasability gates on `availableQuantity > 0`
+ * in three independent places (`service.ts`, the cart route, and the public
+ * list filter). The only field the seller can reach is the one that does not
+ * control availability.
+ *
+ * With 76–93% of competitor catalogues sold out, restock is the main
+ * lifecycle event, not an edge case.
+ *
+ * WHY A DELTA AND NOT `availableQuantity = stockQuantity`: the difference
+ * between the two IS the outstanding reservation — units held by placed-but-
+ * unpaid orders. Overwriting would hand those units back to the shelf and
+ * oversell them. So carry the reservation forward:
+ *
+ *     reserved = prevStock - prevAvailable        (clamped at 0)
+ *     available = nextStock - reserved            (clamped at 0)
+ *
+ * Examples: 10 stock / 10 available, edit to 12 → 12. 10 stock / 7 available
+ * (3 reserved), edit to 12 → 9. Sold out at 0/0, edit to 10 → 10.
+ *
+ * 🛑 Returns `{}` — not a value — whenever the write does not name
+ * `stockQuantity`, or names `availableQuantity` explicitly. The second case
+ * is what keeps the checkout decrement, the stock-restore job and
+ * `updateAvailableQuantity` authoritative: they write `availableQuantity`
+ * directly and must never have it recomputed from a stale `stockQuantity`
+ * underneath them.
+ *
+ * 🛑 EXPORTED, and not merely for tidiness. A BULK stock edit cannot go
+ * through `update` — that is 50 sequential round trips, and Rule #6 budgets a
+ * request at ~3 — so it writes through `batchUpdateEach`. But the delta is
+ * PER DOCUMENT (each product carries its own reservation), which means a bulk
+ * route has to apply this rule itself. Re-deriving it there is Root Cause
+ * #75's shape on the one field whose whole history is that nothing re-synced
+ * it. So the rule is exported and the bulk route calls THIS.
+ *
+ * 🛑 It cannot become a `BaseRepository` write hook, which was the first
+ * thing I tried. A hook receives `{...doc, ...patch}`, where `stockQuantity`
+ * is already the NEXT value — so `prevStock` is gone and `reserved` is
+ * uncomputable. The rule genuinely needs both documents.
+ */
+export function resolveStockResync(current, data) {
+    if (!current)
+        return {};
+    if (!("stockQuantity" in data))
+        return {};
+    // An explicit availableQuantity write wins — see the 🛑 above.
+    if ("availableQuantity" in data)
+        return {};
+    const nextStock = data.stockQuantity;
+    if (typeof nextStock !== "number" || !Number.isFinite(nextStock))
+        return {};
+    const prevStock = typeof current.stockQuantity === "number" ? current.stockQuantity : 0;
+    const prevAvailable = typeof current.availableQuantity === "number" ? current.availableQuantity : prevStock;
+    const reserved = Math.max(0, prevStock - prevAvailable);
+    const nextAvailable = Math.max(0, nextStock - reserved);
+    if (nextAvailable === prevAvailable)
+        return {};
+    return { availableQuantity: nextAvailable };
+}
 export class ProductRepository extends BaseRepository {
     constructor() {
         super(PRODUCT_COLLECTION);
@@ -222,9 +303,8 @@ export class ProductRepository extends BaseRepository {
          * either way. The two can only disagree when one of them is stale, and the
          * derived one is the one that goes stale.
          */
-        const leaf = input.category ||
-            (Array.isArray(input.categorySlugs) && input.categorySlugs[0]) ||
-            null;
+        const assignments = readAssignments(input);
+        const leaf = assignments[0] ?? null;
         /*
          * The brand selector's option value is the brand ROW's id (`brand-beyblade`),
          * but `ProductDocument.brand` is matched by DISPLAY NAME —
@@ -237,32 +317,91 @@ export class ProductRepository extends BaseRepository {
          * left exactly as it was.
          */
         const brandRef = input.brandSlug || input.brand || null;
-        const [catSnap, brandSnap] = await Promise.all([
-            leaf ? cats.doc(leaf).get() : Promise.resolve(null),
-            brandRef ? cats.doc(brandRef).get() : Promise.resolve(null),
-        ]);
-        if (catSnap?.exists) {
-            const cat = catSnap.data();
-            // `parentIds` is ordered root-first / nearest-last (category-tree.ts:107),
-            // and the stored chain is self-first / root-last. Reversing is what makes
-            // the derived value byte-identical to what the seed hand-writes — verified
-            // against products-standard-seed-data.ts:197.
-            out.categorySlugs = [leaf, ...(cat.parentIds ?? []).slice().reverse()];
-            out.category = leaf;
-            const names = [
-                cat.name,
-                ...(cat.ancestors ?? []).map((a) => a?.name).reverse(),
-            ].filter((n) => !!n);
-            if (names.length)
-                out.categoryNames = names;
+        /*
+         * ONE `getAll` for every assignment plus the brand, rather than a read per
+         * assignment. Rule #6 budgets ~3 sequential Firestore round-trips for a
+         * write path and this method is already one of them.
+         */
+        const refs = [...assignments.map((id) => cats.doc(id)), ...(brandRef ? [cats.doc(brandRef)] : [])];
+        const snaps = refs.length > 0 ? await this.db.getAll(...refs) : [];
+        const assignmentSnaps = snaps.slice(0, assignments.length);
+        const brandSnap = brandRef ? (snaps[assignments.length] ?? null) : null;
+        const catSnap = assignmentSnaps[0] ?? null;
+        /*
+         * I1/I2 — resolve every assignment, refuse the disallowed shapes, pick the
+         * default, then derive the ordered closure from all of them.
+         *
+         * 🛑 A row that does not resolve is DROPPED from the assignment list and
+         * warned about, never silently kept: an unresolvable id cannot be checked
+         * against the one-per-root rule and cannot contribute a chain, so keeping
+         * it would put an id in the closure that resolves to no page.
+         */
+        const resolved = [];
+        for (let i = 0; i < assignmentSnaps.length; i += 1) {
+            const snap = assignmentSnaps[i];
+            const id = assignments[i];
+            if (!snap?.exists) {
+                // Never destroy a chain we cannot improve on — see the `else if` below.
+                serverLogger.warn("Product category id does not resolve to a category", { leaf: id });
+                continue;
+            }
+            const d = snap.data();
+            resolved.push({
+                id,
+                name: d.name,
+                rootId: d.rootId,
+                tier: d.tier,
+                isLeaf: d.isLeaf,
+                parentIds: d.parentIds ?? [],
+                ancestorNames: (d.ancestors ?? []).map((a) => a?.name ?? ""),
+            });
         }
-        else if (leaf) {
-            // Never destroy a chain we cannot improve on. A leaf that is not a real
-            // category row is a data problem to report, not a reason to blank the field.
-            serverLogger.warn("Product category id does not resolve to a category", {
-                leaf,
+        if (resolved.length > 0) {
+            assertAssignmentShape(resolved, input.isLot === true, {
+                enforceLeafFiling: ENFORCE_LEAF_FILING,
+                warn: (msg, meta) => serverLogger.warn(msg, { productTitle: input.title, ...meta }),
             });
+            /*
+             * The default's tie-break reads listing counts — and ONLY on a genuine
+             * tie, so a single-assignment product (the overwhelming majority) pays
+             * nothing for it. See `pickDefaultAssignment` for why depth, not count,
+             * is the first criterion.
+             */
+            let counts;
+            const deepest = Math.max(...resolved.map((c) => c.tier ?? -1));
+            if (resolved.filter((c) => (c.tier ?? -1) === deepest).length > 1) {
+                counts = await this.readAssignmentCounts(resolved.map((c) => c.id));
+            }
+            const defaultIdx = pickDefaultAssignment(resolved, counts);
+            const closure = buildTaxonomyClosure(resolved, defaultIdx);
+            /*
+             * 🛑 `categoryIds` is written in the DEFAULT-FIRST order, not the order
+             * the seller picked, so it is parallel to `categoryIdNames` and index 0
+             * agrees with `categorySlugs[0]`. Three fields that must line up, lined
+             * up at the one place that produces all three.
+             */
+            out.categoryIds = closure.categoryIdNames.length
+                ? [resolved[defaultIdx].id, ...resolved.filter((_, i) => i !== defaultIdx).map((c) => c.id)]
+                : resolved.map((c) => c.id);
+            out.categorySlugs = closure.categorySlugs;
+            out.category = closure.categorySlugs[0];
+            if (closure.categoryNames.length)
+                out.categoryNames = closure.categoryNames;
+            if (closure.categoryIdNames.length)
+                out.categoryIdNames = closure.categoryIdNames;
         }
+        /*
+         * 🛑 The old single-leaf block that stood here is GONE, and its two jobs
+         * moved for different reasons:
+         *
+         *   - the chain + names build -> `buildTaxonomyClosure`, because it now has
+         *     to span every assignment while keeping index 0 the default leaf;
+         *   - the lot filing rule -> `assertAssignmentShape`, because it has to run
+         *     per assignment and is now one half of a two-directional rule.
+         *
+         * Its `else if (leaf)` warn also moved, into the resolve loop above, where
+         * it fires per unresolvable assignment instead of only for the first.
+         */
         if (brandSnap?.exists) {
             const brand = brandSnap.data();
             if (brand.categoryType === "brand") {
@@ -277,6 +416,49 @@ export class ProductRepository extends BaseRepository {
         await this.applyInclusivePricing(input, out);
         return out;
     }
+    /**
+     * Listing counts for a handful of category ids, for the default tie-break.
+     *
+     * 🛑 Called ONLY when two assignments tie at the deepest tier, so the common
+     * single-assignment write pays nothing. One `getAll` of at most
+     * `MAX_CATEGORY_ASSIGNMENTS` documents by id — no index, no query.
+     *
+     * 🛑 A missing row is OMITTED from the map rather than defaulted to 0.
+     * `categoryCounts` documents the same rule: `undefined` means "not counted
+     * yet", and defaulting it to zero would let an uncounted node lose a tie it
+     * might have won.
+     *
+     * Reads the collection through `this.db` rather than importing
+     * `categoryCountsRepository` — no repository here imports another feature's
+     * (Root Cause #6/#18), and a raw read by id has neither problem.
+     */
+    async readAssignmentCounts(ids) {
+        const out = new Map();
+        if (ids.length === 0)
+            return out;
+        try {
+            const refs = ids.map((id) => this.db.collection(CATEGORY_COUNTS_COLLECTION).doc(id));
+            const snaps = await this.db.getAll(...refs);
+            for (const snap of snaps) {
+                if (!snap.exists)
+                    continue;
+                const d = snap.data();
+                if (!d.total)
+                    continue;
+                out.set(snap.id, sumCounts(d.total));
+            }
+        }
+        catch (err) {
+            /*
+             * A tie-break is not worth failing a product write over. Falling through
+             * with an empty map drops to level 3 — the order the seller picked — which
+             * is a deterministic answer rather than a wrong one.
+             */
+            void normalizeError(err);
+            serverLogger.warn("Could not read category counts for the default tie-break", { ids });
+        }
+        return out;
+    }
     /**
      * Resolve the GST rate floor, and gross up an ex-tax price if the seller
      * authors that way.
@@ -419,6 +601,24 @@ export class ProductRepository extends BaseRepository {
             "seoTitleTemplate",
             "seoDescriptionTemplate",
             "seoKeywords",
+            /*
+             * C5a — the PACKED parcel figures.
+             *
+             * 🛑 These are resolved up the ancestor chain like everything else here,
+             * and the field they fill is deliberately OPTIONAL on the product: the
+             * figure a carrier bills on is the packed box, not the item, and a bey
+             * is ~30 g against ~300 g boxed. A required product weight would
+             * therefore be an ITEM weight, systematically under-estimating every
+             * booking — and because the booking is capped at the amount collected
+             * from the buyer, systematic under-estimation means silently absorbing
+             * the difference.
+             *
+             * So the category's packed default drives the checkout ESTIMATE, this
+             * fills it when the leaf declares one, the product may refine it, and
+             * the real parcel figure is entered at shipment time.
+             */
+            "weightG",
+            "dimensionsCm",
         ];
         const isEmpty = (v) => v == null || (Array.isArray(v) && v.length === 0);
         const unresolved = () => WANTED.filter((k) => isEmpty(resolved[k]));
@@ -512,6 +712,22 @@ export class ProductRepository extends BaseRepository {
         if (resolved.defaultAuthenticity && !input.authenticity) {
             out.authenticity = resolved.defaultAuthenticity;
         }
+        /*
+         * C5a — fill-blank, never overwrite. A seller who weighed their own packed
+         * box has measured something the category only estimates.
+         *
+         * 🛑 `input.weightG == null`, not `!input.weightG`. A zero is nonsense for
+         * a parcel but it is an explicit value, and the falsy test would replace
+         * it with the category's figure on every save — the same distinction
+         * `gstRate` needs two blocks up, and for the same reason: "nobody said"
+         * and "somebody said zero" are different facts.
+         */
+        if (resolved.weightG != null && input.weightG == null) {
+            out.weightG = resolved.weightG;
+        }
+        if (resolved.dimensionsCm && !input.dimensionsCm) {
+            out.dimensionsCm = { ...resolved.dimensionsCm };
+        }
         /*
          * Features MERGE rather than replace — the field's own contract, and the
          * reason the blader linkage works: a seller who ticks "Japan Import" keeps
@@ -585,65 +801,6 @@ export class ProductRepository extends BaseRepository {
             out.seoKeywords = merged;
         }
     }
-    /**
-     * Keep `availableQuantity` in step when a seller edits `stockQuantity`.
-     *
-     * 🛑 THE BUG THIS CLOSES: A SELLER COULD NOT RESTOCK.
-     *
-     * There are two stock numbers. `stockQuantity` is seller-authored and is the
-     * only one any of the three product forms exposes. `availableQuantity` is
-     * system-owned, seeded from `stockQuantity` **once, at create**, and
-     * thereafter driven by checkout decrements and timeout restores.
-     *
-     * Nothing re-synced them. `updateProduct` is a bare spread, and grep for
-     * `availableQuantity` across `src/app/api/store/products/**` and
-     * `seller-actions.ts` returns ZERO. So: a product sells out
-     * (`availableQuantity: 0`), the seller edits `stockQuantity` 0 → 10, and the
-     * product STAYS UNBUYABLE — purchasability gates on `availableQuantity > 0`
-     * in three independent places (`service.ts`, the cart route, and the public
-     * list filter). The only field the seller can reach is the one that does not
-     * control availability.
-     *
-     * With 76–93% of competitor catalogues sold out, restock is the main
-     * lifecycle event, not an edge case.
-     *
-     * WHY A DELTA AND NOT `availableQuantity = stockQuantity`: the difference
-     * between the two IS the outstanding reservation — units held by placed-but-
-     * unpaid orders. Overwriting would hand those units back to the shelf and
-     * oversell them. So carry the reservation forward:
-     *
-     *     reserved = prevStock - prevAvailable        (clamped at 0)
-     *     available = nextStock - reserved            (clamped at 0)
-     *
-     * Examples: 10 stock / 10 available, edit to 12 → 12. 10 stock / 7 available
-     * (3 reserved), edit to 12 → 9. Sold out at 0/0, edit to 10 → 10.
-     *
-     * 🛑 Returns `{}` — not a value — whenever the write does not name
-     * `stockQuantity`, or names `availableQuantity` explicitly. The second case
-     * is what keeps the checkout decrement, the stock-restore job and
-     * `updateAvailableQuantity` authoritative: they write `availableQuantity`
-     * directly and must never have it recomputed from a stale `stockQuantity`
-     * underneath them.
-     */
-    static resyncAvailableQuantity(current, data) {
-        if (!current)
-            return {};
-        if (!("stockQuantity" in data))
-            return {};
-        // An explicit availableQuantity write wins — see the 🛑 above.
-        if ("availableQuantity" in data)
-            return {};
-        const nextStock = data.stockQuantity;
-        if (typeof nextStock !== "number" || !Number.isFinite(nextStock))
-            return {};
-        const prevStock = typeof current.stockQuantity === "number" ? current.stockQuantity : 0;
-        const prevAvailable = typeof current.availableQuantity === "number" ? current.availableQuantity : prevStock;
-        const reserved = Math.max(0, prevStock - prevAvailable);
-        const nextAvailable = Math.max(0, nextStock - reserved);
-        if (nextAvailable === prevAvailable)
-            return {};
-        return { availableQuantity: nextAvailable };
-    }
     async update(id, data) {
         this.cacheInvalidateForId(id);
         const current = await super.findById(id);
@@ -657,7 +814,7 @@ export class ProductRepository extends BaseRepository {
         const derived = touchesTaxonomy
             ? await this.deriveTaxonomy({ ...current, ...data })
             : {};
-        const stock = ProductRepository.resyncAvailableQuantity(current, data);
+        const stock = resolveStockResync(current, data);
         const merged = { ...current, ...data, ...derived, ...stock };
         const updated = await super.update(id, {
             ...data,
@@ -666,8 +823,58 @@ export class ProductRepository extends BaseRepository {
             searchTxt: buildProductSearchTxt(merged),
         });
         this.cacheSet(updated);
+        await this.syncCategoryCounts(current ?? null, updated);
         return updated;
     }
+    /**
+     * G3b — move the leaf→root listing counters for one product transition.
+     *
+     * 🛑 Called from HERE rather than from a Firestore trigger because
+     * `FieldValue.increment` is atomic but **not idempotent** and a trigger is
+     * at-least-once: a redelivered trigger double-counts permanently and
+     * invisibly. See `repository/category-counts.ts` for the full argument.
+     *
+     * 🛑 And the guard is on (chain, leaf, type, isLot, AVAILABILITY) — not on
+     * the taxonomy alone. `draft → published` changes no `categorySlugs`, so a
+     * taxonomy-only guard would never move the count on the one transition that
+     * matters most, with nothing to notice.
+     *
+     * Availability comes from `isListingRowAvailable`, the SAME predicate the
+     * listing query and `countersReconcile` use, so the incremental and nightly
+     * values can agree. Four partial copies of that predicate is what Root Cause
+     * #73 cost; this module takes the verdict as an argument rather than
+     * recomputing it.
+     */
+    async syncCategoryCounts(before, after) {
+        const now = new Date();
+        const side = (row) => ({
+            delta: row ? describeCountable(row) : null,
+            // A draft or archived row is not "available" and must not be counted —
+            // the count is of what a visitor can actually see, which is why the
+            // badge and the tab agree.
+            countsNow: !!row
+                && row.status === ProductStatusValues.PUBLISHED
+                && isListingRowAvailable(row, now),
+        });
+        const b = side(before);
+        const a = side(after);
+        if (!countsChanged(b, a))
+            return;
+        const patch = buildCountPatch([
+            { delta: b.countsNow ? b.delta : null, sign: -1 },
+            { delta: a.countsNow ? a.delta : null, sign: 1 },
+        ]);
+        await applyCountPatch(this.db, patch, (err) => {
+            // Never fails the product write: a count is a display number, and losing
+            // a seller's publish over an ancestor counter would trade a cosmetic
+            // staleness for real data. The nightly reconciler's `drifted` is how a
+            // missed increment becomes visible.
+            serverLogger.warn("categoryCounts increment failed", {
+                productId: after?.id ?? before?.id,
+                error: err.message,
+            });
+        });
+    }
     async create(input) {
         // Slug = document ID: derive slug from title first, then ensure uniqueness.
         const baseSlug = input.slug || slugify(input.title);
@@ -703,6 +910,7 @@ export class ProductRepository extends BaseRepository {
             .set(prepareForFirestore(productData));
         const created = { id, ...productData };
         this.cacheSet(created);
+        await this.syncCategoryCounts(null, created);
         return created;
     }
     async findByStore(storeId) {
@@ -720,6 +928,32 @@ export class ProductRepository extends BaseRepository {
             .get();
         return snap.docs.map((d) => this.mapDoc(d));
     }
+    /**
+     * I4 — products ASSIGNED to this category, not merely descended from it.
+     *
+     * 🛑 The distinction is the whole point, and the category-delete cascade is
+     * what needs it. `findByCategory` matches the derived CLOSURE, so it also
+     * returns every product in the descendant subtree — those belong to the
+     * children and travel with them when the children are reparented.
+     * `findBy("category", id)` matches only the scalar, i.e. the DEFAULT leaf, so
+     * a product that named this category as its SECOND assignment was invisible
+     * and the delete left a dangling id in its `categoryIds`.
+     *
+     * This matches the assigned list, and falls back to the scalar for every row
+     * written before `categoryIds` existed — two queries, because Firestore
+     * permits one array operator per query and there is no OR across fields.
+     */
+    async findByAssignment(categoryId) {
+        const [assigned, legacy] = await Promise.all([
+            this.getCollection().where("categoryIds", "array-contains", categoryId).get(),
+            this.getCollection().where(PRODUCT_FIELDS.CATEGORY, "==", categoryId).get(),
+        ]);
+        const byId = new Map();
+        for (const d of [...assigned.docs, ...legacy.docs]) {
+            byId.set(d.id, this.mapDoc(d));
+        }
+        return [...byId.values()];
+    }
     /**
      * Published products sharing at least one tag with the given list — "you
      * might also like" style discovery. `array-contains-any` caps at 10 values,
@@ -910,7 +1144,33 @@ export class ProductRepository extends BaseRepository {
     }
     async delete(id) {
         this.cacheInvalidateForId(id);
-        return super.delete(id);
+        /*
+         * 🛑 Read BEFORE deleting, or there is no chain left to decrement and the
+         * counters keep the row forever — the one case where the delta cannot be
+         * recovered from the write itself. One extra read on a delete, which is
+         * the rarest product mutation there is.
+         *
+         * `safeRead`-shaped on purpose: a product that cannot be read must still
+         * be deletable, and the nightly reconciler corrects the count.
+         */
+        let prior = null;
+        try {
+            prior = await super.findById(id);
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            // 🛑 Logged, not swallowed. A failed pre-read means this product's
+            // contribution stays on its ancestors' counters until the nightly
+            // reconciler corrects them — bounded and self-healing, but invisible
+            // unless it is said. `void normalizeError(err)` alone would look handled
+            // while reporting nothing (audit-silent-degrade's normalize theatre).
+            serverLogger.warn("product delete: pre-read failed, counts will drift until reconcile", {
+                productId: id,
+                error: e.message,
+            });
+        }
+        await super.delete(id);
+        await this.syncCategoryCounts(prior, null);
     }
     /**
      * Shared scope construction for `list()` and `countBy*()` — both must narrow
@@ -991,10 +1251,44 @@ export class ProductRepository extends BaseRepository {
         const plan = planSearchTxt(opts?.search);
         if (plan.empty)
             return emptySearchResult();
-        const result = await this.sieveQuery(model, ProductRepository.SIEVE_FIELDS, {
+        /*
+         * ── D2 Fix 2: a MULTI-TERM search over-fetches a window ────────────────
+         *
+         * 🛑 The bug: `refineSearchTxt` used to filter the already-paginated page,
+         * so a two-word search could only ever return matches that happened to fall
+         * inside one page window — rows 51+ matching both terms were unreachable,
+         * and `hasMore: false` asserted there was no page 2. A search returning 7
+         * of 40 real matches reported "7 results" and disabled Next, which reads as
+         * a working search.
+         *
+         * So for a multi-term query the FETCH asks for a bounded window and the
+         * refine slices the requested page out of it. A single-term query is
+         * untouched: its one `array-contains` clause paginates exactly, there is
+         * nothing to refine, and over-fetching would be pure cost.
+         *
+         * 🛑 Bounded, not unbounded (Rule #6): one read of at most
+         * `SEARCH_REFINE_WINDOW`, and when that saturates the result carries
+         * `truncated` so the total renders as a floor rather than a false total.
+         */
+        const isMultiTerm = plan.rest.length > 0;
+        const requestedPage = Math.max(1, Number(model?.page ?? 1) || 1);
+        const requestedPageSize = Math.max(1, Number(model?.pageSize ?? 20) || 20);
+        const result = await this.sieveQuery(
+        /*
+         * The window is requested through the MODEL, not a new `SieveOptions`
+         * field — `sieveQuery` already derives its page from `model.page` /
+         * `model.pageSize`, so overriding them needs no API change and no second
+         * way to express a page size.
+         */
+        isMultiTerm ? { ...model, page: 1, pageSize: SEARCH_REFINE_WINDOW } : model, ProductRepository.SIEVE_FIELDS, {
             baseQuery: this.buildScopedQuery(opts),
             defaultPageSize: 20,
-            maxPageSize: 100,
+            /*
+             * 🛑 `maxPageSize` has to rise with the window or Sieve clamps the
+             * request back to 100 — and the window would silently be a page again,
+             * which is the original bug with a larger constant.
+             */
+            maxPageSize: isMultiTerm ? SEARCH_REFINE_WINDOW : 100,
             aliases: ProductRepository.FILTER_ALIASES,
         });
         // Only the most selective term became the `array-contains` clause, because
@@ -1009,7 +1303,15 @@ export class ProductRepository extends BaseRepository {
         // this page only. That is the known post-pagination-filter debt, not a new
         // invention — reporting the pre-filter total would promise pages that
         // render empty.
-        return refineSearchTxt(result, plan.rest);
+        return refineSearchTxt(result, plan.rest, isMultiTerm
+            ? {
+                page: requestedPage,
+                pageSize: requestedPageSize,
+                // Saturated means more may exist beyond the window, so `total` is a
+                // FLOOR and `truncated` says so.
+                windowSaturated: (result.items?.length ?? 0) >= SEARCH_REFINE_WINDOW,
+            }
+            : undefined);
     }
     /**
      * How many products of each listing type exist within a scope — the numbers
@@ -1140,13 +1442,50 @@ ProductRepository.SIEVE_FIELDS = {
     price: { canFilter: true, canSort: true },
     stockQuantity: { canFilter: true, canSort: true },
     availableQuantity: { canFilter: true, canSort: true },
-    viewCount: { canFilter: true, canSort: true },
+    /*
+     * 🛑 D8 closes F1 #1. `viewCount` was `canFilter`/`canSort` here with NO
+     * writer on any document — measured: absent from all 72 products and all 58
+     * categories — and a Firestore `orderBy` EXCLUDES every document lacking
+     * the ordering field, so `?sort=viewCount` returned zero rows with a valid
+     * index present (Root Cause #100). A5 removed the UI sort and the reachable
+     * field survived.
+     *
+     * Replaced by two fields that have a real nightly writer
+     * (`runProductViewWindows`) and whose names state the window, which
+     * `viewCount` never did — it read as a lifetime figure while nothing
+     * maintained it.
+     */
+    views7d: { canFilter: true, canSort: true },
+    views30d: { canFilter: true, canSort: true },
     currentBid: { canFilter: true, canSort: true },
     bidCount: { canFilter: true, canSort: true },
     bidsHaveStarted: { canFilter: true, canSort: false },
     isSold: { canFilter: true, canSort: true },
     isPartOfBundle: { canFilter: true, canSort: false },
     isTestData: { canFilter: true, canSort: false },
+    /*
+     * The warehouse location — C4.
+     *
+     * 🛑 `physicalLocation` was absent from this config entirely, so a filter
+     * on it was DROPPED SILENTLY: `sieve.ts` sets `throwExceptions: false`, so
+     * `findField()` returning undefined removes the clause rather than
+     * raising. A seller could set a location and then filter by it to no
+     * effect, with nothing anywhere saying so — Root Cause #62's
+     * EMITTED_BUT_UNFILTERABLE shape.
+     *
+     * Nested paths, because that is what Firestore filters on
+     * (`physicalLocation.zone`), and `canSort: false` on all three: sorting by
+     * bin would pair an orderBy with whatever else is filtered and demand a
+     * composite index per combination, which is the trap next door
+     * (Root Cause #59). Browsing a bin is a FILTER, not a sort.
+     *
+     * The primary way to find a location is still `searchTxt` — see
+     * `physicalLocationTokens`. These exist so a dashboard can ask the precise
+     * question ("zone A exactly") where search answers the loose one.
+     */
+    "physicalLocation.zone": { canFilter: true, canSort: false },
+    "physicalLocation.shelf": { canFilter: true, canSort: false },
+    "physicalLocation.bin": { canFilter: true, canSort: false },
     brandSlug: { canFilter: true, canSort: false },
     sublistingCategoryId: { canFilter: true, canSort: false },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },