@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/server/jobs/core/event-draw-reasons.js

@@ -0,0 +1,133 @@
+/**
+ * The ONE reason → {HTTP status, stable code} map for the two event prize-draw
+ * job cores (`assignSpinPrize`, `triggerEventRaffle`).
+ *
+ * ## Why this exists
+ *
+ * Each core returns a `reason` string instead of throwing, and each is reachable
+ * by TWO entry points — a Next.js API route and a Firebase callable handler.
+ * That made four translations of one vocabulary, and all four disagreed:
+ *
+ *   · `api/events/[id]/spin/route.ts`       — had `feature_disabled`, no `not_active`
+ *   · `jobs/handlers/assignSpinPrize.ts`    — `identity_required` → 400 (route said 401),
+ *                                             no `feature_disabled` branch at all
+ *   · `api/admin/events/[id]/trigger-raffle/route.ts` — EVERYTHING → 409
+ *   · `jobs/handlers/triggerEventRaffle.ts` — only 404 / 422
+ *
+ * Root Cause #85 ("a handler reachable by two entry points with different
+ * behaviour"), four times over in one feature. The spin route's own header
+ * already documented the trap and still only fixed its own half.
+ *
+ * ## Two rules that produced real bugs
+ *
+ * 1. 🛑 **A PERMANENT refusal must never take a retryable status.** The spin
+ *    route's fallback was 409 (`ALREADY_EXISTS`), described in its own comment
+ *    as "a benign can't-spin-right-now state". An unlisted permanent reason
+ *    therefore shipped `{code:"ALREADY_EXISTS", error:"<reason>"}` — an envelope
+ *    naming two unrelated things — which the UI rendered as "Spin failed.
+ *    Please try again.", inviting a retry that could never succeed.
+ *
+ * 2. 🛑 **A reason-less result is a SUCCESS to both routes.** Both check
+ *    `if (data.reason && !data.<successField>)`, so a core branch that returned
+ *    early *without* a `reason` fell through to `successResponse`.
+ *    `triggerEventRaffle`'s feature-flag branch did exactly that and answered
+ *    `200 "Raffle triggered"` with no winner. Every non-success branch in either
+ *    core must set a reason from this map.
+ *
+ * There is deliberately NO fallback entry here: `reasonToHttp` is exhaustive
+ * over `EventDrawReason`, so adding a reason without a status is a compile
+ * error rather than a silent 409.
+ */
+import { EVENT_DRAW_ERROR_CODES } from "../../../../errors/error-codes.js";
+export const EVENT_DRAW_REASON = {
+    /** Neither a signed-in user nor a hashed guest identity was supplied. */
+    IDENTITY_REQUIRED: "identity_required",
+    /** Guest attempt on an event that has not opted into guest participation. */
+    LOGIN_REQUIRED: "login_required",
+    EVENT_NOT_FOUND: "event_not_found",
+    /** Draft / paused / cancelled / ended — see each core's status precondition. */
+    NOT_ACTIVE: "not_active",
+    NO_PRIZES_CONFIGURED: "no_prizes_configured",
+    OUTSIDE_SPIN_WINDOW: "outside_spin_window",
+    /** This identity has already consumed its `spinMaxPerUser` allowance. */
+    ALREADY_USED: "already_used",
+    NOT_A_SPIN_WHEEL: "not_a_spin_wheel",
+    NOT_A_RAFFLE: "not_a_raffle",
+    /** A winner is already recorded; a second draw would mean two winners. */
+    ALREADY_TRIGGERED: "already_triggered",
+    NO_ELIGIBLE_ENTRIES: "no_eligible_entries",
+};
+const MAPPING = {
+    [EVENT_DRAW_REASON.IDENTITY_REQUIRED]: {
+        status: 401,
+        code: EVENT_DRAW_ERROR_CODES.IDENTITY_REQUIRED,
+        message: "No user or guest identity was provided",
+    },
+    [EVENT_DRAW_REASON.LOGIN_REQUIRED]: {
+        status: 401,
+        code: EVENT_DRAW_ERROR_CODES.LOGIN_REQUIRED,
+        message: "Sign in to take part in this event",
+    },
+    [EVENT_DRAW_REASON.EVENT_NOT_FOUND]: {
+        status: 404,
+        code: EVENT_DRAW_ERROR_CODES.EVENT_NOT_FOUND,
+        message: "Event not found",
+    },
+    [EVENT_DRAW_REASON.NOT_ACTIVE]: {
+        status: 409,
+        code: EVENT_DRAW_ERROR_CODES.EVENT_NOT_ACTIVE,
+        message: "This event is not running right now",
+    },
+    [EVENT_DRAW_REASON.NO_PRIZES_CONFIGURED]: {
+        status: 422,
+        code: EVENT_DRAW_ERROR_CODES.SPIN_NO_PRIZES,
+        message: "No spin prizes are configured for this event",
+    },
+    [EVENT_DRAW_REASON.OUTSIDE_SPIN_WINDOW]: {
+        status: 403,
+        code: EVENT_DRAW_ERROR_CODES.SPIN_OUTSIDE_WINDOW,
+        message: "This spin wheel is not open right now",
+    },
+    [EVENT_DRAW_REASON.ALREADY_USED]: {
+        status: 409,
+        code: EVENT_DRAW_ERROR_CODES.SPIN_ALREADY_USED,
+        message: "This identity has already used its spins for this event",
+    },
+    [EVENT_DRAW_REASON.NOT_A_SPIN_WHEEL]: {
+        status: 422,
+        code: EVENT_DRAW_ERROR_CODES.NOT_A_SPIN_WHEEL,
+        message: "This event is not a spin wheel",
+    },
+    [EVENT_DRAW_REASON.NOT_A_RAFFLE]: {
+        status: 422,
+        code: EVENT_DRAW_ERROR_CODES.RAFFLE_NOT_A_RAFFLE,
+        message: "This event does not have a raffle",
+    },
+    [EVENT_DRAW_REASON.ALREADY_TRIGGERED]: {
+        status: 409,
+        code: EVENT_DRAW_ERROR_CODES.RAFFLE_ALREADY_DRAWN,
+        message: "A winner has already been drawn for this raffle",
+    },
+    [EVENT_DRAW_REASON.NO_ELIGIBLE_ENTRIES]: {
+        status: 409,
+        code: EVENT_DRAW_ERROR_CODES.RAFFLE_NO_ELIGIBLE_ENTRIES,
+        message: "No eligible entries to draw from",
+    },
+};
+const UNKNOWN = {
+    status: 500,
+    code: EVENT_DRAW_ERROR_CODES.UNKNOWN_REASON,
+    message: "The event could not be processed",
+};
+/**
+ * Translate a core's `reason` into the response shape both entry points use.
+ *
+ * An unrecognised reason maps to **500**, not to the old 409 fallback: a reason
+ * this map has never heard of is a bug in the core, and a 5xx is what gets it
+ * recorded by `onRequestError` instead of being filed as an ordinary conflict.
+ */
+export function reasonToHttp(reason) {
+    if (!reason)
+        return UNKNOWN;
+    return MAPPING[reason] ?? UNKNOWN;
+}

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

@@ -53,17 +53,31 @@ function getStringArrayOpt(baseOpts, key) {
 }
 const LISTERS = {
     products: (m, o) => productRepository.list(m, o),
-    categories: (m) => categoriesRepository.list(m),
-    brands: (m) => categoriesRepository.list({
+    /*
+     * 🛑 These four forward `search`, and did not until 2026-10-17.
+     *
+     * `categoriesRepository.list` and `couponsRepository.list` both accept
+     * `opts?: { search?: string }`, and all four listers below were written
+     * `(m) => repo.list(m)` — so a search term reaching the Function was
+     * DISCARDED and the page came back unfiltered with a 200, while the same
+     * route's local fallback filtered correctly. Exactly the divergence the
+     * comment further down records for orders/reviews/blogPosts/events/stores
+     * and faqs, four collections later: category, brand, coupon and
+     * sublisting-category search.
+     *
+     * Found by `audit-lister-opts-forwarding`, which now blocks the shape.
+     */
+    categories: (m, o) => categoriesRepository.list(m, { search: getStringOpt(o, "search") }),
+    brands: (m, o) => categoriesRepository.list({
         ...m,
         filters: m.filters
             ? `${m.filters},categoryType==brand`
             : "categoryType==brand",
-    }),
+    }, { search: getStringOpt(o, "search") }),
     orders: (m, o) => orderRepository.listAll(m, { search: getStringOpt(o, "search") }),
     reviews: (m, o) => reviewRepository.listAll(m, { search: getStringOpt(o, "search") }),
-    coupons: (m) => couponsRepository.list(m),
-    bids: (m) => bidRepository.list(m),
+    coupons: (m, o) => couponsRepository.list(m, { search: getStringOpt(o, "search") }),
+    bids: (m, o) => bidRepository.list(m, { search: getStringOpt(o, "search") }),
     payouts: (m) => payoutRepository.list(m),
     blogPosts: (m, o) => blogRepository.listAll(m, { search: getStringOpt(o, "search") }),
     events: (m, o) => eventRepository.list(m, { search: getStringOpt(o, "search") }),
@@ -84,13 +98,19 @@ const LISTERS = {
         tags: getStringArrayOpt(o, "tags"),
     }),
     notifications: (m) => notificationRepository.list(m),
-    scammers: (m) => scammerRepository.listAll(m),
-    sublistingCategories: (m) => categoriesRepository.list({
+    /*
+     * `/api/admin/scammers` passes `{ search: q }` to this same method locally —
+     * its route comment records that the identity arrays "were never searched at
+     * all despite the box promising them" before searchTxt. Through the Function
+     * the opt was dropped again, so the two executors disagreed.
+     */
+    scammers: (m, o) => scammerRepository.listAll(m, { search: getStringOpt(o, "search") }),
+    sublistingCategories: (m, o) => categoriesRepository.list({
         ...m,
         filters: m.filters
             ? `${m.filters},categoryType==sublisting`
             : "categoryType==sublisting",
-    }),
+    }, { search: getStringOpt(o, "search") }),
     productFeatures: (m) => productFeaturesRepository.list(m),
     homepageSections: (m) => homepageSectionsRepository.list(m),
     users: (m) => userRepository.list(m),

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

@@ -1,4 +1,5 @@
 import { normalizeError } from "../../../../errors/normalize.js";
+import { ORDER_PII_FIELDS, revealPii } from "../../../../security/index.js";
 import { adminNotificationsRepository, storeRepository, userRepository } from "../../../../repositories/index.js";
 import { decryptPii } from "../../../../security/index.js";
 import { sendWhatsAppBusinessMessage, buildPurchaseAnnouncementMessage, } from "../../../../features/whatsapp-bot/server.js";
@@ -91,7 +92,17 @@ export async function handleOrderCreate(input, ctx) {
      * `decryptPii` was already imported in this file and used for the store
      * owner's phone eleven lines up; the buyer's name was simply missed.
      */
-    const buyerName = decryptPii(order.userName) ?? order.userName ?? "A customer";
+    /*
+     * The NAMED accessor, not a bare `decryptPii` cast.
+     *
+     * This already decrypted and therefore already WORKED — but through a cast
+     * that defeated the brand, so "is every reader converted?" could not be
+     * answered by grepping for `reveal*`. Routing it through `revealOrder` makes
+     * the decision visible in review and in a grep, which is the whole argument
+     * for named accessors over an inline decrypt.
+     */
+    const buyerName = revealPii(order, ORDER_PII_FIELDS).userName ??
+        "A customer";
     const message = buildPurchaseAnnouncementMessage({
         buyerName,
         firstItemName,

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

@@ -10,6 +10,17 @@ export async function handleScamReportCreate(input, ctx) {
     if (reportedBy) {
         try {
             const reporter = await userRepository.findById(reportedBy);
+            /*
+             * REVEALED, because this notification is DELIVERED to the reporter and a
+             * masked address cannot receive mail.
+             *
+             * `findById` stopped decrypting when `UserRepository` went
+             * ciphertext-by-default, so `reporter.email` is an `enc:v1:` blob — it
+             * would have been handed to the mailer verbatim. The old intersection
+             * brand could not object, because `Encrypted<string>` was a subtype of
+             * `string`.
+             */
+            const reporterPlain = reporter ? userRepository.revealUser(reporter) : null;
             await sendNotification({
                 userId: reportedBy,
                 type: "scam_report_update",
@@ -18,8 +29,8 @@ export async function handleScamReportCreate(input, ctx) {
                 message: `Your report for "${name}" has been received. Our team will review it within 48 hours.`,
                 relatedId: scammerId,
                 relatedType: "scammer",
-                userEmail: reporter?.email ?? undefined,
-                userPhone: reporter?.phoneNumber ?? undefined,
+                userEmail: reporterPlain?.email ?? undefined,
+                userPhone: reporterPlain?.phoneNumber ?? undefined,
             });
         }
         catch (err) {

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

@@ -13,6 +13,12 @@ export async function handleScamReportRejected(input, ctx) {
     const name = displayNames?.[0] ?? "Unknown";
     try {
         const reporter = await userRepository.findById(reportedBy);
+        /*
+         * REVEALED, because this notification is DELIVERED to the reporter and a
+         * masked address cannot receive mail. `findById` is ciphertext-by-default,
+         * so passing `.email` straight through handed the mailer an `enc:v1:` blob.
+         */
+        const reporterPlain = reporter ? userRepository.revealUser(reporter) : null;
         await sendNotification({
             userId: reportedBy,
             type: "scam_report_update",
@@ -21,8 +27,8 @@ export async function handleScamReportRejected(input, ctx) {
             message: `Your report for "${name}" could not be verified with the evidence provided. You may submit a new report with additional evidence.`,
             relatedId: scammerId,
             relatedType: "scammer",
-            userEmail: reporter?.email ?? undefined,
-            userPhone: reporter?.phoneNumber ?? undefined,
+            userEmail: reporterPlain?.email ?? undefined,
+            userPhone: reporterPlain?.phoneNumber ?? undefined,
         });
     }
     catch (err) {

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

@@ -13,6 +13,12 @@ export async function handleScamReportVerified(input, ctx) {
     const name = displayNames?.[0] ?? "Unknown";
     try {
         const reporter = await userRepository.findById(reportedBy);
+        /*
+         * REVEALED, because this notification is DELIVERED to the reporter and a
+         * masked address cannot receive mail. `findById` is ciphertext-by-default,
+         * so passing `.email` straight through handed the mailer an `enc:v1:` blob.
+         */
+        const reporterPlain = reporter ? userRepository.revealUser(reporter) : null;
         await sendNotification({
             userId: reportedBy,
             type: "scam_report_update",
@@ -21,8 +27,8 @@ export async function handleScamReportVerified(input, ctx) {
             message: `The report for "${name}" has been verified and published to the Scam Registry. Thank you for helping protect the community.`,
             relatedId: scammerId,
             relatedType: "scammer",
-            userEmail: reporter?.email ?? undefined,
-            userPhone: reporter?.phoneNumber ?? undefined,
+            userEmail: reporterPlain?.email ?? undefined,
+            userPhone: reporterPlain?.phoneNumber ?? undefined,
         });
     }
     catch (err) {

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

@@ -5,9 +5,16 @@
 import { notifyRevalidate } from "./revalidateNotify.js";
 export async function handleStoreWrite(input, ctx) {
     // The search-index sync this used to perform is gone (Firestore queries handle
-    // search now), so the only remaining side-effect is cache invalidation: drop
-    // the ISR entries for this store's page and the stores listing. Reuses the
-    // existing trigger, so this costs no additional invocations, and performs no
-    // Firestore write (Root Cause #92).
+    // search now), so the only remaining side-effect here is cache invalidation:
+    // drop the ISR entries for this store's page and the stores listing. Reuses
+    // the existing trigger, so it costs no additional invocations, and this
+    // function performs no Firestore write.
+    //
+    // 🛑 The HANDLER above it does write one, as of the public search index:
+    // `markSearchIndexDirty` flips a boolean on `searchIndex/manifest`. That is
+    // still safe under Root Cause #92 — a different collection from the one the
+    // trigger watches, with a boolean read-then-write guard — but the old
+    // blanket claim that this trigger writes nothing is no longer true, and a
+    // comment that is false is worse than no comment.
     await notifyRevalidate({ collection: "stores", id: input.storeId }, ctx);
 }

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

@@ -14,10 +14,11 @@ const ORDER_COLLECTION = "orders";
  * — do not change the selection algorithm.
  */
 export async function assignPrizeDrawWinner(ctx, args) {
-    if (ctx.env("FEATURE_PRIZE_DRAWS") !== "true") {
-        ctx.logger.info("FEATURE_PRIZE_DRAWS disabled — skipping winner assignment");
-        return { kind: "not_eligible" };
-    }
+    // The `FEATURE_PRIZE_DRAWS` gate here was deleted 2026-10-19 with the other
+    // four readers — see the header of `assignSpinPrize.ts`. This one was the
+    // worst-shaped of them: it returned `kind: "not_eligible"`, which every
+    // caller treats as "this order does not win anything", so with the env var
+    // unset a paid prize-draw entry was silently recorded as a non-winner.
     const { orderId, productId } = args;
     const orderRef = ctx.db.collection(ORDER_COLLECTION).doc(orderId);
     const productRef = ctx.db.collection(PRODUCT_COLLECTION).doc(productId);

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

@@ -17,10 +17,7 @@ const PRIZE_DRAW_LISTING_TYPE = "prize-draw";
  * "closed".
  */
 export async function runPrizeDrawExpiryReveal(ctx) {
-    if (ctx.env("FEATURE_PRIZE_DRAWS") !== "true") {
-        ctx.logger.info("FEATURE_PRIZE_DRAWS disabled — skipping prize-draw expiry reveal");
-        return;
-    }
+    // `FEATURE_PRIZE_DRAWS` gate deleted 2026-10-19 — see `assignSpinPrize.ts`.
     ctx.logger.info("Prize-draw expiry reveal sweep starting");
     const snap = await ctx.db
         .collection(PRODUCT_COLLECTION)

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

@@ -18,8 +18,7 @@ function isSoldOut(doc) {
  * the draw, then closes it.
  */
 export async function handlePrizeDrawSoldOut(input, ctx) {
-    if (ctx.env("FEATURE_PRIZE_DRAWS") !== "true")
-        return;
+    // `FEATURE_PRIZE_DRAWS` gate deleted 2026-10-19 — see `assignSpinPrize.ts`.
     const { productId, before, after } = input;
     if (!after)
         return;

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

@@ -6,10 +6,13 @@ import { ProductStatusValues } from "../../../../features/products/schemas/fires
  * (coupon.startDate IS NULL OR <= now) filter Firestore can't express.
  */
 export async function runPromotions(_input, ctx) {
-    if (ctx.env("FEATURE_EVENTS") !== "true") {
-        ctx.logger.info("FEATURE_EVENTS disabled — skipping promotions");
-        return { promotedProducts: [], featuredProducts: [], activeCoupons: [] };
-    }
+    /*
+     * `FEATURE_EVENTS` gate deleted 2026-10-19 — see `auctionSettlement.ts`.
+     * Unset in the Functions env, and this branch returned three EMPTY ARRAYS,
+     * which is indistinguishable from "nothing is promoted right now" to every
+     * caller. A refusal shaped like a valid empty answer is the worst of the
+     * nine; the spin route at least produced a 503 somebody could see.
+     */
     ctx.logger.info("Promotions data requested");
     const now = new Date();
     const nowIso = now.toISOString();

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

@@ -0,0 +1,7 @@
+import type { JobContext } from "../runtime/types";
+export declare function runSearchIndexBuild(ctx: JobContext): Promise<void>;
+/**
+ * Force a full rebuild, ignoring the manifest's cadence. For a one-off repair
+ * after a schema bump or a reseed.
+ */
+export declare function runSearchIndexFullRebuild(ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,211 @@
+/*
+ * Core: build the public search index artifact.
+ *
+ * ## 🛑 THE READ BUDGET IS WHY THIS JOB HAS THREE MODES
+ *
+ * Firestore bills per document read regardless of `select()`. A full rebuild
+ * every 15 minutes is `96 × 3,730 ≈ 358,000 reads/day` against a 50,000/day
+ * free tier — seven times over. Hourly is still ~89,000. So:
+ *
+ *   idle        manifest not dirty, full not due     1 read       ~90/day
+ *   incremental dirty: `updatedAt >` per source      13 + changed ~200/day
+ *   full        >24h since the last one              3,730        3,730/day
+ *
+ * ≈ 4,000 reads/day, about 8% of the tier. Measured on production: a full
+ * build is 3,750 reads, 3,589 records, 384 KB raw / 48 KB brotli, in 4.1s.
+ *
+ * 🛑 EVERY RUN LOGS ITS MODE AND READ COUNT. If the incremental path ever
+ * breaks and silently falls back to FULL each cadence, that is 358,000
+ * reads/day and a quota wall — and the only way anyone finds out before the
+ * wall is this line. A job that does the wrong thing cheaply is a bug; one
+ * that does it seven times over the tier is an outage.
+ *
+ * ## Why its own scheduled job rather than folding into an existing one
+ *
+ * `countersReconcile` and `productStatsSync` already run near their 540s
+ * ceiling, and a full rebuild failing inside one of them would take category
+ * metrics down with it. `priceIndexRollup`'s header makes the same argument
+ * for staying separate. CLAUDE.md explicitly accepts ~$0.10/month for a new
+ * distinct-cadence Scheduler job rather than routing around it.
+ *
+ * @tag domain:search
+ * @tag layer:server
+ * @tag pattern:job-core
+ * @tag access:server
+ * @tag consumers:searchIndexBuildHandler
+ * @tag sideEffects:firestore,storage
+ */
+import { getAdminStorage } from "../../../../providers/db-firebase/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { buildFull, buildIncremental, } from "../../features/search/index-build/build.js";
+import { manifestRef, publishArtifact, publishManifestMirror, readManifest, storagePathFor, } from "../../features/search/index-build/artifact-store.js";
+/** How stale the index may get before a reconciling full pass is forced. */
+const FULL_REBUILD_INTERVAL_MS = 24 * 60 * 60 * 1000;
+function dueForFull(manifest, now) {
+    if (!manifest || !manifest.lastFullAt)
+        return true;
+    const last = Date.parse(manifest.lastFullAt);
+    if (!Number.isFinite(last))
+        return true;
+    return now.getTime() - last >= FULL_REBUILD_INTERVAL_MS;
+}
+/**
+ * Fetch the previous artifact so an incremental pass can patch it.
+ *
+ * Returns null on any failure, which makes the caller fall back to a FULL
+ * build. That is the right degradation: a full build is expensive but
+ * correct, whereas patching an artifact we could not read is not possible at
+ * all.
+ */
+async function readPreviousArtifact(storagePath) {
+    try {
+        const bucket = getAdminStorage().bucket();
+        const [buf] = await bucket.file(storagePath).download();
+        return JSON.parse(buf.toString("utf8"));
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * WARN, not silence. Returning null here is a correct degradation — the
+         * caller falls back to a FULL build, which is expensive but right — and
+         * that is exactly why it needs a log line: a permanently unreadable
+         * previous artifact turns every run into a 3,730-read full build and the
+         * only outward sign is the read count creeping up. The fallback hides the
+         * fault, so the log is the one thing that does not.
+         */
+        serverLogger.warn("search index: previous artifact unreadable, falling back to FULL", {
+            storagePath,
+            message: e.message,
+        });
+        return null;
+    }
+}
+export async function runSearchIndexBuild(ctx) {
+    const { db, logger, now } = ctx;
+    const manifest = await readManifest(db);
+    const wantFull = dueForFull(manifest, now);
+    /*
+     * The idle exit. One read, ~90 times a day. Without it the job would do a
+     * 13-query incremental pass every 15 minutes whether or not anything
+     * changed, which is 1,250 reads/day spent proving nothing happened.
+     */
+    if (!wantFull && manifest && manifest.dirty !== true) {
+        logger.info("search index: idle (not dirty, full not due)", { reads: 1 });
+        return;
+    }
+    const version = (manifest?.version ?? 0) + 1;
+    let result;
+    let mode = "full";
+    if (!wantFull && manifest) {
+        const previous = await readPreviousArtifact(manifest.storagePath);
+        if (previous) {
+            const since = new Date(manifest.builtAt);
+            result = await buildIncremental(db, previous, since, version, now);
+            mode = "incremental";
+        }
+    }
+    if (!result) {
+        result = await buildFull(db, version, now);
+        mode = "full";
+    }
+    const { artifact, stats } = result;
+    const published = await publishArtifact(getAdminStorage().bucket(), artifact);
+    const next = {
+        schema: artifact.schema,
+        version,
+        builtAt: artifact.builtAt,
+        lastFullAt: mode === "full" ? artifact.builtAt : (manifest?.lastFullAt ?? artifact.builtAt),
+        storagePath: published.storagePath,
+        recordCount: artifact.r.length,
+        bytes: published.bytes,
+        perType: stats.perType,
+        /*
+         * Cleared LAST, after the artifact is live — clearing it first would lose
+         * every write that arrived while this build was running.
+         *
+         * 🛑 And NOT cleared at all if any source threw. An incremental pass skips
+         * a failing source by design (the previous values stay, which is correct
+         * and slightly stale), but clearing `dirty` on top of that would mean the
+         * next run exits idle and those types never recover until the daily full
+         * pass — a partial index reported as a clean one. Staying dirty costs one
+         * retry per cadence and is self-healing.
+         *
+         * This mattered immediately: the first incremental run against production
+         * failed on every source with a `where` clause, for a missing composite
+         * index, and without this it would have published a mostly-empty patch
+         * and called it done.
+         */
+        dirty: stats.failed > 0,
+    };
+    await manifestRef(db).set(next, { merge: true });
+    /*
+     * Firestore first (the next build reads it), the public mirror second (the
+     * browser reads it). See `publishManifestMirror` for why a failure here is
+     * logged rather than thrown.
+     */
+    await publishManifestMirror(getAdminStorage().bucket(), next);
+    /*
+     * 🛑 The line that makes a runaway visible. `reads` is the number that has
+     * to stay inside the budget, and `mode` is what explains it.
+     */
+    const line = stats.failed > 0 ? logger.warn : logger.info;
+    line("search index built", {
+        mode,
+        version,
+        reads: stats.reads,
+        // 🛑 Surfaced, not swallowed. A non-zero count means the artifact is
+        // incomplete for those types and the manifest stays dirty for a retry.
+        failedSources: stats.failed,
+        records: artifact.r.length,
+        dropped: stats.dropped,
+        bytes: published.bytes,
+        prunedVersions: published.pruned,
+        durationMs: stats.durationMs,
+    });
+}
+/**
+ * Force a full rebuild, ignoring the manifest's cadence. For a one-off repair
+ * after a schema bump or a reseed.
+ */
+export async function runSearchIndexFullRebuild(ctx) {
+    const { db, logger, now } = ctx;
+    const manifest = await readManifest(db);
+    const version = (manifest?.version ?? 0) + 1;
+    try {
+        const { artifact, stats } = await buildFull(db, version, now);
+        const published = await publishArtifact(getAdminStorage().bucket(), artifact);
+        const next = {
+            schema: artifact.schema,
+            version,
+            builtAt: artifact.builtAt,
+            lastFullAt: artifact.builtAt,
+            storagePath: published.storagePath,
+            recordCount: artifact.r.length,
+            bytes: published.bytes,
+            perType: stats.perType,
+            dirty: false,
+        };
+        await manifestRef(db).set(next, { merge: true });
+        /*
+         * 🛑 The mirror belongs on BOTH paths. This one is the manual repair
+         * entry point — the one somebody reaches for precisely when the index is
+         * wrong — so a rebuild that fixed the artifact and left every browser
+         * pointed at the broken version would be the worst possible outcome of
+         * running it.
+         */
+        await publishManifestMirror(getAdminStorage().bucket(), next);
+        logger.info("search index FULL rebuild complete", {
+            version,
+            reads: stats.reads,
+            records: artifact.r.length,
+            bytes: published.bytes,
+            path: storagePathFor(version),
+        });
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        logger.error("search index FULL rebuild failed", { message: e.message });
+        throw err;
+    }
+}

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

@@ -1,6 +1,38 @@
 /**
  * Core: select a raffle winner for an event using `crypto.randomInt()`. Pool
  * logic keys off the event's `raffleType`.
+ *
+ * ## Three things in here had never worked
+ *
+ * 1. **The pool query could not match any entry created by this app.** It
+ *    asked for `status == "CONFIRMED"` — a real field with a real admin
+ *    workflow (`AdminAllEventEntriesView`'s Confirm / Waitlist / Cancel row
+ *    actions) but with NO writer at creation time. `enterEvent` never set it
+ *    and neither did the seed, so the pool was empty unless an admin had
+ *    hand-confirmed every entry one row at a time — on a raffle seeded with
+ *    1,892 entries. Every draw returned `no_eligible_entries`; the raffle had
+ *    never once been drawable.
+ *
+ *    The predicate is now `reviewStatus == "approved"`: written on every entry
+ *    path, already indexed `(eventId, reviewStatus, submittedAt DESC)`, and
+ *    auto-approved for raffles by `enterEvent`. `status` keeps its RSVP
+ *    meaning and is deliberately NOT the gate — see the note on both fields in
+ *    `constants/field-names.ts`.
+ *
+ * 2. **`drawsPermitted: 1` was not enforced.** The already-drawn check and the
+ *    winner write sat outside any transaction, so two concurrent admin clicks
+ *    both saw no winner and both wrote — two winners for one prize. The
+ *    check-and-write is now inside `runTransaction`, following the sibling
+ *    core `prizeDrawAssignWinner`.
+ *
+ * 3. **The winner was never told.** A winner was recorded and the only way to
+ *    find out was to revisit the event page.
+ *
+ * The `FEATURE_PRIZE_DRAWS` gate that used to open this function was deleted
+ * 2026-10-19 — see the header of `assignSpinPrize.ts`. Its branch here was the
+ * second-worst shaped of the nine: it returned early with **no `reason`**, and
+ * the route decides success by `if (data.reason && !data.raffleWinnerUserId)`,
+ * so a disabled feature answered `200 "Raffle triggered"` with no winner.
  */
 import type { JobContext } from "../runtime/types";
 export interface TriggerEventRaffleInput {
@@ -9,9 +41,12 @@ export interface TriggerEventRaffleInput {
     topN?: number;
 }
 export interface TriggerEventRaffleResult {
+    /** The canonical DOCUMENT ID, even when the caller passed a slug. */
     eventId: string;
     raffleWinnerUserId?: string;
     raffleWinnerDisplayName?: string;
+    /** The prize coupon's CODE, resolved at draw time and recorded on the event. */
+    rafflePrizeCouponCode?: string;
     raffleEntryCount: number;
     alreadyTriggered?: boolean;
     reason?: string;