@mohasinac/appkit 4.45.0 → 4.46.0

package/dist/_internal/server/jobs/core/onCategoryWrite.js

@@ -23,6 +23,13 @@ import { normalizeError } from "../../../../errors/normalize.js";
  *                   equal and does nothing. The cascade stops.
  *   MOVE          → writes `positionDirty`, which is also not `parentIds`, so its
  *                   own re-entry likewise does nothing. One extra hop, then stop.
+ *   RENAME/MOVE   → (I4) also ENQUEUES `categoryTaxonomyBackfill`. That write
+ *                   goes to `jobs`, a different collection, so it cannot
+ *                   re-enter here at all. The job then writes `products` and,
+ *                   on a rename, descendant `categories` rows — and those DO
+ *                   re-enter, as updates carrying an unchanged `name` and
+ *                   `parentIds`, so both branches compare equal and nothing
+ *                   cascades. One hop per descendant, then stop.
  *
  * The guard is STRUCTURAL, not a value comparison — that is what makes it stronger
  * than #92's. `onShipmentHeaderWrite` recomputed and rewrote the same derived field
@@ -31,8 +38,9 @@ import { normalizeError } from "../../../../errors/normalize.js";
  * forever. Here there is nothing to compare: the handler cannot write the field it
  * branches on.
  *
- * 🛑 If you ever make this handler write `parentIds`, it becomes a true loop. Do
- * not — a move is deliberately deferred to the nightly reconcile for this reason.
+ * 🛑 If you ever make this handler write `parentIds` OR `name`, it becomes a
+ * true loop — `name` joined `parentIds` as a branch condition in I4. Do not; a
+ * move is deliberately deferred to the nightly reconcile for this reason.
  *
  * Not free, though: creating one category writes to its siblings, its ancestors and
  * itself, and each of those writes spawns a no-op invocation. A full reseed of the
@@ -46,6 +54,7 @@ import { normalizeError } from "../../../../errors/normalize.js";
  * carries correct DFS coordinates skips the branch entirely.
  */
 import { FieldValue } from "firebase-admin/firestore";
+import { enqueueJob } from "../../../../features/jobs/actions/enqueue-job.js";
 import { BATCH_LIMIT } from "../handlers/messages.js";
 const CATEGORIES = "categories";
 async function shiftPositions(ctx, threshold, delta, excludeId) {
@@ -92,6 +101,34 @@ async function getMaxPosition(ctx, excludeId) {
     }
     return 0;
 }
+/**
+ * I4 — hand a rename or a reparent to the backfill job.
+ *
+ * Extracted to module scope rather than inlined, because inline it sat at
+ * brace-depth 6 and `audit-code-quality` is right to refuse that: the
+ * interesting part of this function is the self-write argument in the header,
+ * and burying a try/catch four levels in obscures it.
+ */
+async function enqueueTaxonomyBackfill(ctx, categoryId, kind) {
+    try {
+        const { jobId } = await enqueueJob({
+            jobType: "categoryTaxonomyBackfill",
+            payload: { categoryId, kind },
+            requestedBy: "system:onCategoryWrite",
+        });
+        ctx.logger.info("Category taxonomy backfill enqueued", { categoryId, kind, jobId });
+    }
+    catch (err) {
+        void normalizeError(err);
+        /*
+         * Non-fatal, and deliberately so: a failed enqueue must not fail the
+         * category write the admin just made. The cost of the miss is a stale
+         * subtree until someone re-saves — which the nightly `countersReconcile`
+         * reports as drift rather than hiding.
+         */
+        ctx.logger.error("Category taxonomy backfill could not be enqueued", err, { categoryId });
+    }
+}
 export async function handleCategoryWrite(input, ctx) {
     const { categoryId, before, after } = input;
     // Drop the ISR entries for this category/brand/bundle page and the listings
@@ -206,7 +243,10 @@ export async function handleCategoryWrite(input, ctx) {
             const afterParents = after.parentIds ?? [];
             const beforeParent = beforeParents[beforeParents.length - 1] ?? null;
             const afterParent = afterParents[afterParents.length - 1] ?? null;
-            if (beforeParent !== afterParent) {
+            const moved = beforeParent !== afterParent;
+            const renamed = before.name !== after.name &&
+                typeof after.name === "string";
+            if (moved) {
                 await ctx.db
                     .collection(CATEGORIES)
                     .doc(categoryId)
@@ -217,6 +257,36 @@ export async function handleCategoryWrite(input, ctx) {
                     toParent: afterParent,
                 });
             }
+            /*
+             * I4 — a RENAME had no handler at all, and that was the live gap.
+             *
+             * `ancestors[]` on every descendant, and `categoryNames` on every product
+             * in the subtree, are denormalised copies of THIS node's name. Both feed
+             * `searchTxt` — `buildCategorySearchTxt` indexes ancestor names so that
+             * typing "burst" reaches a Lost Longinus leaf, and
+             * `buildProductSearchTxt` indexes `categoryNames`. So renaming a node
+             * left its whole subtree findable by the OLD name and not the new one,
+             * with this node's own page looking perfectly correct.
+             *
+             * A reparent is enqueued too. `reparentSubtree` already calls
+             * `rewriteProductChains` synchronously, which fixes the chains — but it is
+             * unbounded inside a request, and it does not rebuild `searchTxt`. The job
+             * is idempotent, so running after it costs only the rows it still has to
+             * fix.
+             *
+             * 🛑 THE SELF-WRITE GUARD STILL HOLDS, and it must be checked rather than
+             * assumed: this handler is a `documentWritten` trigger on `categories`
+             * that writes back to `categories` (Root Cause #92's shape, 1,017,548
+             * invocations in 24h). `enqueueJob` writes to `jobs` — a DIFFERENT
+             * collection — so it cannot re-enter here. The job itself writes
+             * `products` and, on a rename, descendant `categories` rows: those DO
+             * re-enter, as updates whose `parentIds` and `name` are unchanged, so both
+             * branches above compare equal and nothing cascades. The structural rule
+             * is unchanged: this handler must never write `parentIds` or `name`.
+             */
+            if (moved || renamed) {
+                await enqueueTaxonomyBackfill(ctx, categoryId, renamed ? "rename" : "reparent");
+            }
         }
     }
     catch (err) {

package/dist/_internal/server/jobs/core/onProductWrite.js

@@ -12,18 +12,50 @@ const UNAVAILABLE_PRODUCT_STATUSES = new Set([
     ProductStatusValues.ARCHIVED,
 ]);
 void UNAVAILABLE_PRODUCT_STATUSES;
-function getEffectiveCategory(doc) {
+/**
+ * I3 — the ASSIGNED categories, where `own` moves.
+ *
+ * 🛑 The selection order must stay byte-identical to `describeCountable` and to
+ * `countersReconcile.tallyProduct`. All three read the same two fields in the
+ * same order, and if any one of them disagreed the nightly recount would
+ * "correct" a live count that was right — drift that is invisible precisely
+ * because the job overwrites rather than compares.
+ */
+function getEffectiveCategories(doc) {
     if (!doc)
-        return null;
+        return [];
+    const ids = doc.categoryIds;
+    if (Array.isArray(ids) && ids.length > 0)
+        return ids.filter(Boolean);
     const categorySlugs = doc.categorySlugs;
-    if (Array.isArray(categorySlugs) && categorySlugs.length > 0)
-        return categorySlugs[0];
-    return doc.category ?? null;
+    if (Array.isArray(categorySlugs) && categorySlugs.length > 0) {
+        return [categorySlugs[0]].filter(Boolean);
+    }
+    const scalar = doc.category;
+    return scalar ? [scalar] : [];
 }
-async function getParentIds(categoryId) {
-    if (!categoryId)
+/**
+ * Each assignment paired with its ancestor chain, read from the LIVE tree.
+ *
+ * 🛑 From the category documents, never from the product's stored closure —
+ * that is what makes a reparent self-heal here as well as in the nightly job.
+ * One read per assignment, in parallel, and at most
+ * `MAX_CATEGORY_ASSIGNMENTS` of them.
+ */
+async function withParents(categoryIds) {
+    if (categoryIds.length === 0)
         return [];
-    return (await categoriesRepository.findById(categoryId))?.parentIds ?? [];
+    return Promise.all(categoryIds.map(async (id) => ({
+        id,
+        parentIds: (await categoriesRepository.findById(id))?.parentIds ?? [],
+    })));
+}
+/** True when the two assignment lists differ as SETS, not as ordered arrays. */
+function assignmentsMoved(before, after) {
+    if (before.length !== after.length)
+        return true;
+    const a = new Set(after);
+    return before.some((id) => !a.has(id));
 }
 /**
  * 🛑 THIS IS A CROSS-COLLECTION TRIGGER AND THAT IS THE SAFETY ARGUMENT.
@@ -46,17 +78,21 @@ async function getParentIds(categoryId) {
  * own count equals its rollup by construction.
  */
 async function dispatchProductWriteEvent(p) {
-    const { productId, beforeCategory, afterCategory, beforeBrand, afterBrand, beforeStoreId, afterStoreId, isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx } = p;
-    /** Stage one category (and, if given, one brand) at `sign` × 1 item. */
-    const stage = (batch, categoryId, brandId, parentIds, auction, sign) => {
+    const { productId, beforeCategories, afterCategories, beforeBrand, afterBrand, beforeStoreId, afterStoreId, isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx } = p;
+    /** Stage every assignment (and, if given, one brand) at `sign` x 1 item. */
+    const stage = (batch, assignments, brandId, auction, sign) => {
         const productDelta = auction ? 0 : sign;
         const auctionDelta = auction ? sign : 0;
-        if (categoryId) {
-            categoriesRepository.updateMetricsInBatch(batch, categoryId, parentIds, productDelta, auctionDelta, productId);
-        }
-        if (brandId) {
-            categoriesRepository.updateMetricsInBatch(batch, brandId, [], productDelta, auctionDelta, productId);
-        }
+        if (assignments.length === 0 && !brandId)
+            return;
+        /*
+         * ONE call, which aggregates per document id — see
+         * `updateMetricsForAssignmentsInBatch`. Looping the single-category version
+         * instead would stage two writes on a shared ancestor, and Firestore
+         * rejects a batch containing two writes to the same document, losing every
+         * increment in it rather than just the duplicate.
+         */
+        categoriesRepository.updateMetricsForAssignmentsInBatch(batch, assignments, productDelta, auctionDelta, productId, brandId);
     };
     /*
      * `batch.update()` REJECTS a missing document, and a batch is atomic — so one
@@ -71,26 +107,26 @@ async function dispatchProductWriteEvent(p) {
         await batch.commit();
         ctx.logger.info(what, { productId, ...meta });
     };
-    if (isDelete && wasPublished && (beforeCategory || beforeBrand)) {
+    if (isDelete && wasPublished && (beforeCategories.length > 0 || beforeBrand)) {
         const batch = ctx.db.batch();
-        stage(batch, beforeCategory, beforeBrand, await getParentIds(beforeCategory ?? ""), beforeIsAuction, -1);
-        await commit(batch, "Decremented counters on hard-delete", { category: beforeCategory, brand: beforeBrand, storeId: beforeStoreId });
+        stage(batch, await withParents(beforeCategories), beforeBrand, beforeIsAuction, -1);
+        await commit(batch, "Decremented counters on hard-delete", { categories: beforeCategories, brand: beforeBrand, storeId: beforeStoreId });
         if (beforeStoreId)
             await storeRepository.incrementTotalProducts(beforeStoreId, -1);
         return;
     }
-    if (!wasPublished && isPublished && (afterCategory || afterBrand)) {
+    if (!wasPublished && isPublished && (afterCategories.length > 0 || afterBrand)) {
         const batch = ctx.db.batch();
-        stage(batch, afterCategory, afterBrand, await getParentIds(afterCategory ?? ""), isAuction, 1);
-        await commit(batch, "Incremented counters on publish", { category: afterCategory, brand: afterBrand, storeId: afterStoreId });
+        stage(batch, await withParents(afterCategories), afterBrand, isAuction, 1);
+        await commit(batch, "Incremented counters on publish", { categories: afterCategories, brand: afterBrand, storeId: afterStoreId });
         if (afterStoreId)
             await storeRepository.incrementTotalProducts(afterStoreId, 1);
         return;
     }
-    if (wasPublished && !isPublished && (beforeCategory || beforeBrand)) {
+    if (wasPublished && !isPublished && (beforeCategories.length > 0 || beforeBrand)) {
         const batch = ctx.db.batch();
-        stage(batch, beforeCategory, beforeBrand, await getParentIds(beforeCategory ?? ""), beforeIsAuction, -1);
-        await commit(batch, "Decremented counters on unpublish", { category: beforeCategory, brand: beforeBrand, storeId: beforeStoreId });
+        stage(batch, await withParents(beforeCategories), beforeBrand, beforeIsAuction, -1);
+        await commit(batch, "Decremented counters on unpublish", { categories: beforeCategories, brand: beforeBrand, storeId: beforeStoreId });
         if (beforeStoreId)
             await storeRepository.incrementTotalProducts(beforeStoreId, -1);
         return;
@@ -104,7 +140,7 @@ async function dispatchProductWriteEvent(p) {
      * through every branch and silently leave both brand rows wrong.
      */
     if (wasPublished && isPublished) {
-        const categoryMoved = beforeCategory !== afterCategory;
+        const categoryMoved = assignmentsMoved(beforeCategories, afterCategories);
         const brandMoved = beforeBrand !== afterBrand;
         /*
          * A listing can also change WHICH counter it belongs in without moving at
@@ -125,16 +161,10 @@ async function dispatchProductWriteEvent(p) {
          * correctly does not move — the item did not come or go, it changed shape.
          */
         if (!categoryMoved && !brandMoved) {
-            const parents = await getParentIds(afterCategory ?? "");
             const productDelta = isAuction ? -1 : 1;
             const auctionDelta = isAuction ? 1 : -1;
             const batch = ctx.db.batch();
-            if (afterCategory) {
-                categoriesRepository.updateMetricsInBatch(batch, afterCategory, parents, productDelta, auctionDelta, productId);
-            }
-            if (afterBrand) {
-                categoriesRepository.updateMetricsInBatch(batch, afterBrand, [], productDelta, auctionDelta, productId);
-            }
+            categoriesRepository.updateMetricsForAssignmentsInBatch(batch, await withParents(afterCategories), productDelta, auctionDelta, productId, afterBrand);
             await commit(batch, "Listing type changed", {
                 productId,
                 from: beforeIsAuction ? "auction" : "product",
@@ -143,15 +173,35 @@ async function dispatchProductWriteEvent(p) {
             return;
         }
         const [beforeParents, afterParents] = await Promise.all([
-            getParentIds(categoryMoved ? beforeCategory ?? "" : ""),
-            getParentIds(categoryMoved ? afterCategory ?? "" : ""),
+            withParents(categoryMoved ? beforeCategories : []),
+            withParents(categoryMoved ? afterCategories : []),
         ]);
+        /*
+         * TWO BATCHES, not one, and this is the I3 change that matters most.
+         *
+         * The -1 and the +1 both touch the rows that did NOT move: a listing
+         * re-filed from one leaf to a sibling shares every ancestor above them, and
+         * a product gaining a SECOND assignment keeps its first one entirely. In
+         * one batch those are two writes to the same document, which Firestore
+         * rejects outright — so the whole re-file would throw and BOTH counters
+         * would be left wrong.
+         *
+         * It worked before only because a single assignment's -1 and +1 were staged
+         * with ids that happened to be disjoint whenever the branch ran at all.
+         *
+         * Sequential commits are not atomic together: a crash between them leaves
+         * the decrement applied and the increment missing. That is the right trade,
+         * because it is self-healing — `countersReconcile` rewrites from scratch
+         * nightly and reports it as `drifted` — whereas a rejected batch is silent.
+         */
+        const outBatch = ctx.db.batch();
+        stage(outBatch, beforeParents, brandMoved ? beforeBrand : null, beforeIsAuction, -1);
+        await outBatch.commit();
         const batch = ctx.db.batch();
-        stage(batch, categoryMoved ? beforeCategory : null, brandMoved ? beforeBrand : null, beforeParents, beforeIsAuction, -1);
-        stage(batch, categoryMoved ? afterCategory : null, brandMoved ? afterBrand : null, afterParents, isAuction, 1);
+        stage(batch, afterParents, brandMoved ? afterBrand : null, isAuction, 1);
         await commit(batch, "Re-filed product", {
-            fromCategory: categoryMoved ? beforeCategory : undefined,
-            toCategory: categoryMoved ? afterCategory : undefined,
+            fromCategories: categoryMoved ? beforeCategories : undefined,
+            toCategories: categoryMoved ? afterCategories : undefined,
             fromBrand: brandMoved ? beforeBrand : undefined,
             toBrand: brandMoved ? afterBrand : undefined,
         });
@@ -195,8 +245,8 @@ export async function handleProductWrite(input, ctx) {
     // mapDoc() normalizes this on read, but a raw trigger snapshot bypasses that,
     // so a product written via categorySlugs-only paths would otherwise silently
     // no-op category metrics here. Prefer categorySlugs[0], fall back to legacy category.
-    const beforeCategory = getEffectiveCategory(before);
-    const afterCategory = getEffectiveCategory(after);
+    const beforeCategories = getEffectiveCategories(before);
+    const afterCategories = getEffectiveCategories(after);
     /*
      * `brandSlug` is the brand ROW's document id in this same `categories`
      * collection. `brand` is the display NAME and is not a key — CLAUDE.md's
@@ -238,7 +288,7 @@ export async function handleProductWrite(input, ctx) {
     const isDelete = !after;
     try {
         await dispatchProductWriteEvent({
-            productId, beforeCategory, afterCategory, beforeBrand, afterBrand,
+            productId, beforeCategories, afterCategories, beforeBrand, afterBrand,
             beforeStoreId, afterStoreId,
             isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx,
         });

package/dist/_internal/server/jobs/core/productViewWindows.d.ts

@@ -0,0 +1,2 @@
+import type { JobContext } from "../runtime/types";
+export declare function runProductViewWindows(ctx: JobContext): Promise<void>;

package/dist/_internal/server/jobs/core/productViewWindows.js

@@ -0,0 +1,173 @@
+/*
+ * WHY: visit data was collected and thrown away. `PageViewTracker` is mounted
+ *      on ~30 public surfaces and writes one `pageViews` bucket per entity per
+ *      day — and NOTHING joined those buckets to a product, so no seller could
+ *      see how many people looked at their listing. Meanwhile `viewCount` was
+ *      `canFilter`/`canSort` in the products Sieve config with no writer on any
+ *      document, so a `?sort=viewCount` returned ZERO rows (Root Cause #100).
+ *
+ * WHAT: a nightly recompute of each product's trailing 7- and 30-day view
+ *       counts onto `views7d` / `views30d`.
+ *
+ * EXPORTS: runProductViewWindows
+ *
+ * ── 🛑 WHY THIS IS A SEPARATE PASS FROM `pageViewRollup` ───────────────────
+ *
+ * They cannot share a read. `pageViewRollup` ACCUMULATES: it folds only buckets
+ * it has not seen, because the ones it has are then deleted by the prune, so a
+ * recompute-from-scratch would make its total walk backwards. A trailing window
+ * is the opposite shape — it must re-read the last 30 days EVERY run, because
+ * yesterday's 30-day window is not today's. Mixing them would break
+ * `throughDate`'s invariant, which is the one thing making that job
+ * re-runnable.
+ *
+ * ── 🛑 IT ENUMERATES PRODUCTS, NOT BUCKETS ────────────────────────────────
+ *
+ * Root Cause #102's lesson, which cost 19 of 65 category rows: a reconciler
+ * that walks the EVENTS can only ever add. A product that stops being viewed
+ * must have its figure fall to 0, and that product has no bucket in the window
+ * at all — so the pass is driven by the product list and a missing bucket means
+ * zero rather than "leave it alone".
+ *
+ * ── 🛑 ABSENT STILL MEANS "NOT ROLLED UP", NOT ZERO ───────────────────────
+ *
+ * The first run writes every product including the ones at 0, so after it
+ * absence is unambiguous. Before it, a reader must distinguish the two — which
+ * is why the renderers check `typeof x === "number"` and not truthiness.
+ *
+ * @tag domain:analytics
+ * @tag layer:job
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:pageViewRollup scheduled function
+ * @tag sideEffects:writes products.views7d / products.views30d
+ */
+import { pageViewsRepository } from "../../../../features/analytics/repository/page-views.repository.js";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore.js";
+/** The longer of the two windows, so one read serves both. */
+const WINDOW_DAYS = 30;
+const SHORT_WINDOW_DAYS = 7;
+/**
+ * 🛑 A bound, because `listInRange` has none.
+ *
+ * One bucket per product per day: 95 products over 30 days is ~2,850 documents
+ * today, which is fine, and 5,000 products would be 150,000 — well past what a
+ * 540s function should read in one pass. Saturating this is reported rather
+ * than silently truncating the windows, because a truncated window is a wrong
+ * number that looks exactly like a right one.
+ */
+const MAX_BUCKETS = 20000;
+/** Matches `countersReconcile`'s scan page, and stays under the 500-op batch. */
+const PAGE_SIZE = 200;
+function dayKey(offsetDays) {
+    const d = new Date();
+    d.setUTCDate(d.getUTCDate() + offsetDays);
+    return d.toISOString().slice(0, 10);
+}
+export async function runProductViewWindows(ctx) {
+    /*
+     * Through YESTERDAY, not today. Today's bucket is still being written to, so
+     * including it makes the figure move during the day for no reason a reader
+     * could explain — and the rollup beside this one draws the same line for the
+     * same reason.
+     */
+    const through = dayKey(-1);
+    const from = dayKey(-WINDOW_DAYS);
+    const shortFrom = dayKey(-SHORT_WINDOW_DAYS);
+    /*
+     * No `.catch(() => [])`. An empty range is a legitimate zero, so a swallowed
+     * failure would write a confident "nobody looked at this" across the whole
+     * catalogue — and that is indistinguishable from the truth. Let it throw.
+     */
+    const buckets = await pageViewsRepository.listInRange(from, through, "product");
+    if (buckets.length >= MAX_BUCKETS) {
+        /*
+         * Refuse rather than write. A partial window is a wrong number with a
+         * confident shape, and the whole point of this pass is that the figure can
+         * be trusted. The prune keeps the collection bounded, so this firing is a
+         * signal that the window or the catalogue has outgrown one query.
+         */
+        ctx.logger.error("productViewWindows: bucket cap hit, refusing to write", {
+            buckets: buckets.length,
+            cap: MAX_BUCKETS,
+            from,
+            through,
+        });
+        return;
+    }
+    const views30 = new Map();
+    const views7 = new Map();
+    for (const b of buckets) {
+        const n = Number(b.count) || 0;
+        if (!Number.isFinite(n) || n <= 0)
+            continue;
+        views30.set(b.entityId, (views30.get(b.entityId) ?? 0) + n);
+        // One pass, two windows: the 7-day figure is the tail of the same read.
+        if (b.date >= shortFrom)
+            views7.set(b.entityId, (views7.get(b.entityId) ?? 0) + n);
+    }
+    /*
+     * 🛑 Driven by the PRODUCT list. A product with no bucket in the window gets
+     * 0 written, which is the half a bucket-driven pass cannot do — see the
+     * header.
+     */
+    let scanned = 0;
+    let written = 0;
+    /*
+     * `ctx.db` with `orderBy("__name__")` + `startAfter`, which is exactly what
+     * `countersReconcile` does over this same collection. Bounded reads,
+     * unbounded total coverage — and no new repository method, because the one I
+     * first reached for did not exist.
+     */
+    let cursor = null;
+    for (;;) {
+        let q = ctx.db
+            .collection(PRODUCT_COLLECTION)
+            .orderBy("__name__")
+            .limit(PAGE_SIZE);
+        if (cursor)
+            q = q.startAfter(cursor);
+        const page = await q.get();
+        if (page.empty)
+            break;
+        /*
+         * One batch per page. `batchUpdateEach` caps at Firestore's 500 operations
+         * and PAGE_SIZE is 200, so a page can never exceed it.
+         */
+        const batch = ctx.db.batch();
+        let inBatch = 0;
+        for (const doc of page.docs) {
+            scanned += 1;
+            const data = doc.data();
+            const next7 = views7.get(doc.id) ?? 0;
+            const next30 = views30.get(doc.id) ?? 0;
+            // Skip a no-op. `countersReconcile` does the same: a product already at
+            // these figures costs no write rather than a wasted one.
+            if (data.views7d === next7 && data.views30d === next30)
+                continue;
+            batch.update(doc.ref, { views7d: next7, views30d: next30 });
+            inBatch += 1;
+        }
+        if (inBatch > 0) {
+            await batch.commit();
+            written += inBatch;
+        }
+        cursor = page.docs[page.docs.length - 1];
+        if (page.size < PAGE_SIZE)
+            break;
+    }
+    ctx.logger.info("productViewWindows: complete", {
+        from,
+        through,
+        buckets: buckets.length,
+        productsScanned: scanned,
+        productsWritten: written,
+        /*
+         * Reported because on a quiet day a non-zero `written` with a zero
+         * `buckets` would mean the pass is zeroing the whole catalogue — which is
+         * correct if nobody visited, and a signal if the tracker has stopped
+         * recording. Neither is visible from a success line alone.
+         */
+        productsWithViews: views30.size,
+    });
+}

package/dist/_internal/server/jobs/core/testDataCleanup.d.ts

@@ -14,7 +14,7 @@ import type { JobContext } from "../runtime/types";
  * (This used to be shared with testerSandboxRefresh.ts, which was removed when
  * the tester runner took over fixture state — see scheduled.ts.)
  */
-export declare const TEST_DATA_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events", "offers"];
+export declare const TEST_DATA_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events"];
 export interface TestDataCleanupOptions {
     /** true = wipe every isTestData:true doc regardless of testDataExpiresAt (manual force-purge). */
     force?: boolean;

package/dist/_internal/server/jobs/core/testDataCleanup.js

@@ -15,7 +15,33 @@ import { BID_FIELDS } from "../../../../constants/field-names.js";
  * (This used to be shared with testerSandboxRefresh.ts, which was removed when
  * the tester runner took over fixture state — see scheduled.ts.)
  */
-export const TEST_DATA_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events", "offers"];
+/*
+ * 🛑 `offers` was in this list and could only ever match ZERO rows.
+ *
+ * `OfferDocument` (features/seller/schemas/firestore.ts) does not declare
+ * `isTestData` at all, and `getTestDataRefs` queries on exactly that field — so
+ * the entry read as coverage and swept nothing. Measured live before removal:
+ * 10 offers, 0 carrying the field. Removed rather than given the field, because
+ * no offer fixture has ever needed hiding from the public.
+ *
+ * 🛑 And a wider measurement worth recording, because it changes how to read
+ * this job: **zero documents in ANY of the five remaining collections carry
+ * `isTestData` either** — 416 categories, 70 products, 20 blogPosts, 12 events,
+ * 4 stores, all absent. So this sweep is DORMANT in production, which is
+ * correct rather than broken: the only two `isTestData` fixtures the seed ever
+ * had were deleted 2026-10-10, and nothing has needed hiding since.
+ *
+ * 🛑 Do NOT confuse this list with `seedPurpose`. They answer different
+ * questions and conflating them hides the catalogue:
+ *
+ *   isTestData + testDataExpiresAt  -> may the PUBLIC see this row? (this job)
+ *   seedPurpose                     -> may a PURGE delete this row?
+ *
+ * A demo product is `seedPurpose: "test"` and fully visible; a sandbox fixture
+ * is both `test` AND `isTestData`. `audit-seed-purpose` R6 now asserts every
+ * entry here declares the field, so the `offers` shape cannot return.
+ */
+export const TEST_DATA_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events"];
 const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
 export async function runTestDataCleanup(ctx, opts = {}) {
     const cutoff = opts.force ? null : new Date();

package/dist/_internal/server/jobs/handlers/pageViewRollup.d.ts

@@ -1,2 +1,22 @@
 import type { ScheduleHandler } from "../runtime/types";
+/**
+ * Two passes over `pageViews`, in one scheduled function.
+ *
+ * 🛑 One function because the Firebase budget row prices each registered
+ * Cloud Scheduler job at ~$0.10/month and says to fold new periodic work into
+ * an existing cadence where it is a natural fit. These two read the same
+ * collection on the same night, so it is.
+ *
+ * 🛑 But they are two CORES, not one, because their read shapes are opposites:
+ * the rollup ACCUMULATES (it must only see buckets it has not folded, or its
+ * total walks backwards as the prune catches up) while the windows RECOMPUTE
+ * (yesterday's 30-day window is not today's). Sharing a read would break
+ * `throughDate`, which is the only thing making the rollup re-runnable.
+ *
+ * 🛑 Sequential, and the rollup goes FIRST. It is the one whose failure loses
+ * data permanently — a bad read there advances `throughDate` past days it never
+ * counted. The windows are a pure recompute and tomorrow's run fixes any miss,
+ * so they are the half that can safely be second. `Promise.all` would let a
+ * windows failure mask a rollup failure in the same rejection.
+ */
 export declare const pageViewRollupHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/pageViewRollup.js

@@ -1,2 +1,26 @@
 import { runPageViewRollup } from "../core/pageViewRollup.js";
-export const pageViewRollupHandler = runPageViewRollup;
+import { runProductViewWindows } from "../core/productViewWindows.js";
+/**
+ * Two passes over `pageViews`, in one scheduled function.
+ *
+ * 🛑 One function because the Firebase budget row prices each registered
+ * Cloud Scheduler job at ~$0.10/month and says to fold new periodic work into
+ * an existing cadence where it is a natural fit. These two read the same
+ * collection on the same night, so it is.
+ *
+ * 🛑 But they are two CORES, not one, because their read shapes are opposites:
+ * the rollup ACCUMULATES (it must only see buckets it has not folded, or its
+ * total walks backwards as the prune catches up) while the windows RECOMPUTE
+ * (yesterday's 30-day window is not today's). Sharing a read would break
+ * `throughDate`, which is the only thing making the rollup re-runnable.
+ *
+ * 🛑 Sequential, and the rollup goes FIRST. It is the one whose failure loses
+ * data permanently — a bad read there advances `throughDate` past days it never
+ * counted. The windows are a pure recompute and tomorrow's run fixes any miss,
+ * so they are the half that can safely be second. `Promise.all` would let a
+ * windows failure mask a rollup failure in the same rejection.
+ */
+export const pageViewRollupHandler = async (ctx) => {
+    await runPageViewRollup(ctx);
+    await runProductViewWindows(ctx);
+};

package/dist/_internal/shared/actions/action-registry.js

@@ -797,6 +797,42 @@ export const ACTIONS = {
             kind: "secondary",
             permissions: ["seller", "admin"],
         },
+        /*
+         * D13 — assemble a complete bey from component listings, and part one back
+         * out. Registered here rather than inlined because Rule #7 is not
+         * negotiable and because PART-OUT IS DESTRUCTIVE: it decrements a sellable
+         * listing, so it carries a `confirmation` and a `danger` kind. An action
+         * with `destructive: true` and no confirmation executes immediately with no
+         * warning, which is what has cost data in prior sessions.
+         */
+        "assemble-from-parts": {
+            iconKey: "create",
+            id: "store.assemble-from-parts",
+            label: "Assemble from parts",
+            ariaLabel: "Build this listing from component parts in your inventory",
+            description: "Build one or more of this listing from parts you already hold. Each component's stock is decremented; units already reserved by unpaid orders are never consumed.",
+            kind: "secondary",
+            permissions: ["seller", "admin"],
+        },
+        "part-out-listing": {
+            iconKey: "delete",
+            id: "store.part-out-listing",
+            label: "Part out",
+            ariaLabel: "Break this listing down into its component parts",
+            description: "Break this listing down and add its parts back to inventory. The complete listing's stock is decremented.",
+            kind: "danger",
+            permissions: ["seller", "admin"],
+            confirmation: {
+                title: "Part this out?",
+                /*
+                 * Names what is LOST and what is GAINED, because a confirmation that
+                 * only says "are you sure" leaves the seller to guess which direction
+                 * the stock moves.
+                 */
+                body: "This listing's stock goes down and each component's stock goes up. It cannot be undone automatically — re-assembling is a separate action.",
+                confirmLabel: "Part out",
+            },
+        },
         "set-stock": {
             iconKey: "edit",
             id: "store.set-stock",