@mohasinac/appkit 4.43.0 → 4.45.0

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

@@ -1,19 +1,35 @@
-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 { matchesAllSearchTerms, parseSearchTxtQuery, } from "../../../utils/search-txt";
+import { normalizeError } from "../../../errors/normalize.js";
+import { increment, serverTimestamp } from "../../../contracts/field-ops.js";
+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, 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";
-// Collection NAME only — deliberately not `categoriesRepository`. See
-// deriveTaxonomy()'s header for why this is a raw read.
-import { CATEGORIES_COLLECTION } from "../../categories/schemas/firestore";
-import { PRODUCT_FIELDS } from "../../../constants/field-names";
+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.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.js";
+// Pure money math — no Firestore, no server-only imports.
+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.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
@@ -52,6 +68,113 @@ function buildListingKindClause(kind, inverted) {
     const op = inverted ? "!=" : "==";
     return `${PRODUCT_FIELDS.LISTING_TYPE}${op}${canonical}`;
 }
+/**
+ * Fill an SEO template's slots from what the write actually carries.
+ *
+ * 🛑 A SERVER-SIDE subset on purpose, and smaller than the picker's.
+ *
+ * The seller form's template picker resolves nine slots because it has the
+ * whole draft in hand — the condition LABEL, the category path, the tier-1
+ * series, the tier-2 system. This runs inside a repository write with only the
+ * input and what `deriveTaxonomy` has just derived, and fetching more to fill
+ * an SEO title would spend a round trip on a field a seller can overwrite in
+ * one keystroke.
+ *
+ * So the slots it cannot fill resolve to EMPTY and the sentence closes around
+ * them, which `interpolate` guarantees — never the literal `{{series}}`. The
+ * templates in `category-content.ts` are written to read correctly with any
+ * slot missing for exactly this reason.
+ *
+ * 🛑 No `{{price}}` slot, here or anywhere: a price in free text is an
+ * ungated public price `<GatedPrice>` cannot wrap, and `audit-guest-price-leak`
+ * R2 blocks it.
+ */
+function interpolateDefaults(template, input, derived) {
+    const names = derived.categoryNames ?? input.categoryNames ?? [];
+    return interpolate(template, {
+        title: input.title,
+        brand: derived.brand ?? input.brand,
+        condition: input.condition,
+        // `categoryNames` is self-first / root-last, so [0] is the leaf and the
+        // path reads root-first the way a breadcrumb does.
+        category: names[0],
+        categoryPath: names.length ? [...names].reverse().join(" › ") : undefined,
+        series: names[names.length - 2],
+        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);
@@ -127,7 +250,21 @@ export class ProductRepository extends BaseRepository {
      * feature's repository, and the reason is the Turbopack import-chain trap
      * (Root Cause #6/#18) — a raw collection read has neither problem.
      */
-    async deriveTaxonomy(input) {
+    async deriveTaxonomy(input, 
+    /**
+     * Whether this is the product's FIRST write.
+     *
+     * 🛑 Load-bearing for one field — see `applyCategoryDefaults`' features
+     * block. Inheriting a merge-shaped default on every save makes a seller's
+     * REMOVAL un-stickable: they untick an inherited feature, the next save
+     * that touches the category silently puts it back, and nothing reports it.
+     * Merge is right for create and wrong for update.
+     *
+     * Defaults to `false`, which is the safe direction: the worst a missed
+     * `true` can do is skip an inheritance the seller can tick themselves,
+     * whereas a wrongly-passed `true` resurrects a value they deleted.
+     */
+    isCreate = false) {
         const out = {};
         const cats = this.db.collection(CATEGORIES_COLLECTION);
         /*
@@ -206,8 +343,354 @@ export class ProductRepository extends BaseRepository {
                     out.brand = brand.name;
             }
         }
+        if (catSnap?.exists) {
+            await this.applyCategoryDefaults(input, out, catSnap, isCreate);
+        }
+        await this.applyInclusivePricing(input, out);
         return out;
     }
+    /**
+     * Resolve the GST rate floor, and gross up an ex-tax price if the seller
+     * authors that way.
+     *
+     * ## The rate resolution order, in full
+     *
+     *  1. the product's own `gstRate`, if a human set one — including `0`, a
+     *     deliberate exemption;
+     *  2. the CATEGORY's rate via `taxCodeId` → `taxCodes`, applied just above
+     *     by `applyCategoryDefaults`. **This is the mechanism**, and the ~330-node
+     *     forest carries a tax code on every listing branch, so it answers for
+     *     effectively the whole catalogue;
+     *  3. `DEFAULT_GST_RATE` — a floor, warned about, never a feature.
+     *
+     * 🛑 Step 3 fires only when steps 1 and 2 both came up empty, which means
+     * the category has no tax code — and THAT is the defect to fix. The measure
+     * of success is that this warning never appears. It exists because the
+     * alternative fails asymmetrically: with prices tax-inclusive, treating an
+     * unrated item as 0% hands the seller the full amount and leaves us owing
+     * tax on money already paid out, which is C0's bug in miniature.
+     *
+     * ## The gross-up
+     *
+     * A store with `pricesIncludeGst: false` types EX-TAX prices, so the typed
+     * number is converted ONCE here and stored tax-inclusive like every other
+     * price. No money path branches on the flag; see `taxableFromInclusive`.
+     *
+     * Gated on the write actually carrying a price, so a stock decrement or a
+     * status flip pays nothing for this — the same discipline `update` already
+     * applies to the taxonomy derivation itself.
+     */
+    async applyInclusivePricing(input, out) {
+        const rate = out.gstRate ?? input.gstRate;
+        if (rate == null) {
+            out.gstRate = DEFAULT_GST_RATE;
+            serverLogger.warn("[gst] no rate from the product or its category — applying DEFAULT_GST_RATE; the category is missing a taxCodeId", { category: input.category, defaultRate: DEFAULT_GST_RATE });
+        }
+        /*
+         * Only a write that sets a price can need converting. `input.price` is the
+         * merged current-document-plus-patch (see `update`), so an unrelated save
+         * would re-convert an already-converted price — which is why the guard is
+         * on the PATCH carrying a price, resolved by the callers below.
+         */
+        if (input.price == null || !input.storeId)
+            return;
+        const storeSnap = await this.db
+            .collection(STORE_COLLECTION)
+            .doc(input.storeId)
+            .get();
+        const store = storeSnap.exists
+            ? storeSnap.data()
+            : null;
+        // Absent means inclusive — the documented default, and the one that keeps
+        // every existing listing's price meaning exactly what it meant before.
+        if (store?.pricesIncludeGst !== false)
+            return;
+        const effectiveRate = out.gstRate ?? input.gstRate ?? DEFAULT_GST_RATE;
+        if (effectiveRate <= 0)
+            return; // an exempt item has nothing to gross up
+        out.price = grossFromTaxable(input.price, effectiveRate);
+        /*
+         * 🛑 `compareAtPrice` is deliberately NOT converted here, because it does
+         * not exist. `SellerProductShell`'s pricing section lists it among its
+         * `fields` and renders an input for it, but `ProductDocument` has no such
+         * property — so whatever a seller types there is stripped by the schema and
+         * never stored. A declared-but-unpersisted form field is its own defect
+         * (and a strike-through price is a money figure, so it would need the same
+         * gross-up the day it becomes real); logged rather than silently worked
+         * around, since converting a field that is discarded would be theatre.
+         */
+        serverLogger.info("[gst] grossed up an ex-tax price for a pricesIncludeGst:false store", {
+            storeId: input.storeId,
+            rate: effectiveRate,
+        });
+    }
+    /**
+     * Hand down what the category declares: the tax code, the spec rows, the
+     * in-the-box list, the inherited features and the SEO templates.
+     *
+     * ## 🛑 Why this is server-side and not a form default
+     *
+     * GST is tax CORRECTNESS. A client-side default is bypassable by all ~14
+     * write paths, and the defect this closes is recorded in our own source:
+     * *"0 of 40 live orders had a `gstAmount`, and the order page's Tax row had
+     * never rendered."* The rate has to be applied where every path funnels, and
+     * that is here.
+     *
+     * ## 🛑 The three behaviours are different, and the difference is the design
+     *
+     *   WRITTEN     tax, specifications, inTheBox, features — written when the
+     *               product omits them.
+     *   FILL-BLANK  seo* — fills only an empty field, never overwrites a
+     *               seller's own words.
+     *   ADVISORY    priceGuidance — NEVER touched here. It renders as a hint
+     *               beside the price input and nothing else. Writing a suggested
+     *               price onto `price` would be the platform setting a seller's
+     *               price, which is not a default, it is a decision.
+     *
+     * ## 🛑 Resolution is PER FIELD across the ancestor chain
+     *
+     * Not "the nearest category that declares a `productDefaults` object wins".
+     * B5's named-model leaves carry `defaultFeatures` (the blader, the battle
+     * type, the spin) while the tax code, the spec rows and the price band live
+     * on the tier-3 LINE above them. An object-level "nearest wins" would hand a
+     * Dragoon G its blader and NO TAX CODE — silently deriving no GST, which is
+     * the quiet under-charging failure the whole tax-code indirection exists to
+     * prevent.
+     *
+     * ## Cost
+     *
+     * One `getAll` over at most four ancestors, fired only when the leaf leaves
+     * something unresolved, plus one read for the tax code. With the leaf+brand
+     * read that is three round trips worst case against Rule #6's ~3 budget —
+     * and `update` only re-derives when a write names a taxonomy field, so a
+     * stock decrement or a status flip pays none of it.
+     */
+    async applyCategoryDefaults(input, out, 
+    /*
+     * The real snapshot type, not a `{ data(): unknown }` shape. The first
+     * draft used the latter and `audit-unknown-leakage` was right to reject
+     * it: `unknown` at a parameter boundary is how a callee ends up casting,
+     * and the one cast here is already narrow and stated.
+     */
+    catSnap, isCreate) {
+        const cats = this.db.collection(CATEGORIES_COLLECTION);
+        const leafData = catSnap.data();
+        const resolved = { ...(leafData.productDefaults ?? {}) };
+        /*
+         * Which fields still need an answer. `priceGuidance` is deliberately absent
+         * from this list — it is never applied, so walking ancestors to find one
+         * would be a round trip spent on a value this function will not use.
+         */
+        const WANTED = [
+            "taxCodeId",
+            "specifications",
+            "defaultFeatures",
+            "defaultCondition",
+            "defaultAuthenticity",
+            "inTheBox",
+            "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]));
+        if (unresolved().length > 0 && (leafData.parentIds ?? []).length > 0) {
+            /*
+             * `parentIds` is root-first / nearest-last, so walk it REVERSED —
+             * nearest ancestor first. One `getAll`, not a read per level: four
+             * sequential `doc().get()` calls would be four round trips and breach
+             * Rule #6 on a path that already spends two.
+             */
+            const nearestFirst = [...(leafData.parentIds ?? [])].reverse();
+            const snaps = await this.db.getAll(...nearestFirst.map((id) => cats.doc(id)));
+            for (const snap of snaps) {
+                if (unresolved().length === 0)
+                    break;
+                if (!snap.exists)
+                    continue;
+                const d = snap.data()
+                    .productDefaults;
+                if (!d)
+                    continue;
+                for (const k of unresolved()) {
+                    if (!isEmpty(d[k]))
+                        resolved[k] = d[k];
+                }
+            }
+        }
+        // ── tax: resolve the REFERENCE to a SNAPSHOT on the product ────────────
+        /*
+         * 🛑 `input.gstRate == null`, NEVER `!input.gstRate`.
+         *
+         * Zero is a DELIBERATE exemption — `tax-exempt-0` exists for live plants
+         * and animals — and a falsy test would overwrite every one of them with
+         * the category's rate. The schema's own comment at `gstRate` says so.
+         */
+        const needsRate = input.gstRate == null;
+        const needsHsn = !input.hsnCode;
+        if (resolved.taxCodeId && (needsRate || needsHsn)) {
+            const taxSnap = await this.db
+                .collection(TAX_CODES_COLLECTION)
+                .doc(resolved.taxCodeId)
+                .get();
+            const tax = taxSnap.exists
+                ? taxSnap.data()
+                : null;
+            if (tax?.isActive) {
+                if (needsRate && tax.gstRate != null)
+                    out.gstRate = tax.gstRate;
+                if (needsHsn && tax.hsnCode)
+                    out.hsnCode = tax.hsnCode;
+            }
+            else {
+                /*
+                 * 🛑 A dangling or deactivated tax code must be LOUD, because its
+                 * silent failure mode is under-charging.
+                 *
+                 * `findResolvable` answers null for both cases and the correct
+                 * handling is "leave `gstRate` alone" — so every later listing under
+                 * that category derives NO TAX and the order invoices zero. Nothing
+                 * errors, the save succeeds, and the shortfall only surfaces in a
+                 * filing. DELETE already refuses while a category references a code;
+                 * this covers a code deactivated after the fact.
+                 */
+                serverLogger.warn("Category tax code does not resolve to an active taxCodes row", {
+                    taxCodeId: resolved.taxCodeId,
+                    productId: input.id,
+                });
+            }
+        }
+        // ── WRITTEN: only when the product omits them ──────────────────────────
+        if (resolved.specifications?.length && !input.specifications?.length) {
+            out.specifications = resolved.specifications.map((s) => ({ ...s }));
+        }
+        /*
+         * 🛑 `inTheBox` is deliberately NOT written to the product.
+         *
+         * `ProductDocument` has no such field, and the plan's suggestion —
+         * `out.features = d.inTheBox` — predates the vocabulary merge: `features`
+         * now holds feature IDS, so writing "Beyblade top, Manual (where
+         * supplied)" into it would put prose where `array-contains` expects
+         * `feature-nib`, breaking every facet on that product and tokenising
+         * "where" and "supplied" into its search index.
+         *
+         * It stays a CATEGORY-side value, read by the description-template
+         * endpoint (C2b) to fill the "What's in the box?" block the new-in-box
+         * body already renders. That is the only consumer it ever needed.
+         */
+        if (resolved.defaultCondition && !input.condition) {
+            out.condition = resolved.defaultCondition;
+        }
+        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
+         * it and also gets `feature-blader-tyson-granger` from the Dragoon G leaf.
+         *
+         * 🛑 BUT ONLY ON CREATE, OR WHEN THE PRODUCT CARRIES NONE. This was a real
+         * defect in C2a as shipped.
+         *
+         * `update` calls `deriveTaxonomy({ ...current, ...data })`, so `input`
+         * holds the stored document merged with the patch — which is exactly what
+         * makes every other guard here correct, because a seller's edited
+         * `specifications` or `condition` is present and the `!input.X` test is
+         * false. Features were the one field that did not test presence: they
+         * merged unconditionally. So a seller who UNTICKED an inherited feature —
+         * removing `feature-type-attack` because their build is actually defense —
+         * had it silently re-added by the next save that touched the category or
+         * the brand. The removal could not stick and nothing reported it.
+         *
+         * On update the seller's array IS the answer. They have had the chance to
+         * curate it, and a removal is a decision. An update that carries no
+         * features at all still inherits, so a listing created before its category
+         * had defaults picks them up the first time it is edited.
+         *
+         * Capped at MAX_FEATURES_PER_PRODUCT because `features[]` feeds
+         * `buildProductSearchTxt`, which truncates at 600 tokens SILENTLY — an
+         * unbounded list would evict real title tokens nobody chose to drop. The
+         * product's OWN features are kept first so it is always the inherited ones
+         * that fall off the end.
+         */
+        const mayInheritFeatures = isCreate || !input.features?.length;
+        if (resolved.defaultFeatures?.length && mayInheritFeatures) {
+            const merged = [...(input.features ?? [])];
+            for (const f of resolved.defaultFeatures) {
+                if (!merged.includes(f))
+                    merged.push(f);
+            }
+            if (merged.length > MAX_FEATURES_PER_PRODUCT) {
+                serverLogger.warn("Category default features exceeded the per-product cap", {
+                    productId: input.id,
+                    kept: MAX_FEATURES_PER_PRODUCT,
+                    dropped: merged.length - MAX_FEATURES_PER_PRODUCT,
+                });
+            }
+            out.features = merged.slice(0, MAX_FEATURES_PER_PRODUCT);
+        }
+        // ── FILL-BLANK: a template never overwrites what a seller wrote ─────────
+        const title = input.title ?? "";
+        if (resolved.seoTitleTemplate && !input.seoTitle && title) {
+            out.seoTitle = interpolateDefaults(resolved.seoTitleTemplate, input, out);
+        }
+        if (resolved.seoDescriptionTemplate && !input.seoDescription && title) {
+            out.seoDescription = interpolateDefaults(resolved.seoDescriptionTemplate, input, out);
+        }
+        /*
+         * 🛑 Same create-only gate as features, and for the same reason — plus
+         * this one also contradicted the stated contract three lines above it.
+         * "FILL-BLANK: seo* fills only an empty field, never overwrites a
+         * seller's own words" was true of `seoTitle` and `seoDescription` and
+         * false of `seoKeywords`, which merged on every save. A seller who
+         * deleted an inherited keyword got it back.
+         *
+         * Lower stakes than features — nobody watches their keyword list the way
+         * they watch a type chip — which is precisely why it would have gone
+         * unnoticed indefinitely.
+         */
+        if (resolved.seoKeywords?.length && (isCreate || !input.seoKeywords?.length)) {
+            const merged = [...(input.seoKeywords ?? [])];
+            for (const k of resolved.seoKeywords)
+                if (!merged.includes(k))
+                    merged.push(k);
+            out.seoKeywords = merged;
+        }
+    }
     async update(id, data) {
         this.cacheInvalidateForId(id);
         const current = await super.findById(id);
@@ -221,10 +704,12 @@ export class ProductRepository extends BaseRepository {
         const derived = touchesTaxonomy
             ? await this.deriveTaxonomy({ ...current, ...data })
             : {};
-        const merged = { ...current, ...data, ...derived };
+        const stock = resolveStockResync(current, data);
+        const merged = { ...current, ...data, ...derived, ...stock };
         const updated = await super.update(id, {
             ...data,
             ...derived,
+            ...stock,
             searchTxt: buildProductSearchTxt(merged),
         });
         this.cacheSet(updated);
@@ -248,7 +733,7 @@ export class ProductRepository extends BaseRepository {
         // what makes a UI-created product reachable from its own category page at
         // all. A seed row already carrying the correct chain derives to the same
         // value, so this is a no-op for every existing fixture.
-        const derived = await this.deriveTaxonomy(input);
+        const derived = await this.deriveTaxonomy(input, true);
         const withTaxonomy = { ...input, ...derived };
         const productData = {
             ...withTaxonomy,
@@ -528,10 +1013,69 @@ export class ProductRepository extends BaseRepository {
         return baseQuery;
     }
     async list(model, opts) {
-        const result = await this.sieveQuery(model, ProductRepository.SIEVE_FIELDS, {
+        /*
+         * 🛑 THE EMPTY GUARD — a non-blank query that yields NO usable token must
+         * return nothing, not everything.
+         *
+         * `parseSearchTxtQuery` normalises away punctuation, so `"!!!"`, `"—"`,
+         * `"???"` and `"@#$"` all reduce to `[]`. `buildScopedQuery` then takes its
+         * `searchTxt.length > 0` branch as FALSE and emits **no clause at all**, so
+         * the query falls back to the caller's other filters — on the public
+         * listing that is `status==published` — and **the entire published
+         * catalogue is returned as search results.**
+         *
+         * `products` was the only one of the twelve MIGRATED collections still
+         * hand-rolling this. The other eleven go through `planSearchTxt`, whose
+         * whole reason for existing is this guard (see the header of
+         * `utils/search-txt-query.ts`); adopting it here closes the gap rather
+         * than adding a twelfth private copy of the rule.
+         *
+         * `planSearchTxt` is built on the same `parseSearchTxtQuery` this method
+         * already called, and `plan.head`/`plan.rest` are exactly the previous
+         * `searchTxt[0]`/`.slice(1)` — so apart from the guard this is behaviour-
+         * identical, which is what makes it safe for a path four executors share.
+         */
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        /*
+         * ── 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
@@ -540,24 +1084,21 @@ export class ProductRepository extends BaseRepository {
         // nothing actually refined them — so "red dranzer" returned everything
         // matching "dranzer" and the second word did nothing at all.
         //
-        // Same shape as faqsRepository.list, deliberately: one implementation of
-        // "AND the remaining terms" that both collections read the same way.
-        const terms = parseSearchTxtQuery(opts?.search ?? "");
-        const extraTerms = terms.slice(1);
-        if (extraTerms.length === 0)
-            return result;
-        const items = result.items.filter((p) => matchesAllSearchTerms(p.searchTxt, extraTerms));
-        // `total` becomes a FLOOR once rows are dropped after the page was cut —
-        // it counts this page only. That is the known post-pagination-filter debt
-        // (Phase 5), not a new invention: reporting the pre-filter total here would
-        // promise pages that render empty.
-        return {
-            ...result,
-            items,
-            total: items.length,
-            totalPages: items.length === 0 ? 0 : 1,
-            hasMore: false,
-        };
+        // `refineSearchTxt` is that AND-refine, shared with the other eleven
+        // migrated collections. It also owns the `total`-becomes-a-FLOOR
+        // bookkeeping: once rows are dropped after the page was cut, `total` counts
+        // 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, 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
@@ -577,21 +1118,21 @@ export class ProductRepository extends BaseRepository {
             aliases: ProductRepository.FILTER_ALIASES,
         });
     }
-    async incrementViewCount(productId) {
-        try {
-            await this.db
-                .collection(this.collection)
-                .doc(productId)
-                .update({
-                [PRODUCT_FIELDS.VIEW_COUNT]: increment(1),
-            });
-            // Fire-and-forget analytics: a lost view increment changes no rendered
-            // content, so it must never break the product read path it rides with.
-        }
-        catch (_err) {
-            void normalizeError(_err);
-        }
-    }
+    /*
+     * 🛑 `incrementViewCount` DELETED 2026-10-10 — zero callers since
+     * 2026-08-31.
+     *
+     * It was removed from the product-detail render path then, for two good
+     * reasons recorded in `_internal/server/features/products/data.ts`: it was a
+     * Firestore WRITE on every render (Rule #6), and it double-counted against
+     * `pageViews`, which is now the single counter. The method itself was left
+     * behind, so `viewCount` has had a writer in the codebase and none in
+     * practice ever since — which is how a "Most Viewed" sort and a "0 views"
+     * column both shipped against a field no document has.
+     *
+     * Keeping a writer nobody calls is what makes the dead field look alive.
+     * `pageViews` is the counter; roll it up rather than reviving this.
+     */
     /**
      * Cloud Functions: find published auctions whose end date has already passed.
      * Used by the auction settlement job to finalize expired auctions.
@@ -695,6 +1236,29 @@ ProductRepository.SIEVE_FIELDS = {
     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 },